Authentication

Val Town’s REST API supports Bearer Token authentication.

You can create and manage your API tokens on the API Tokens page.

If you’re using the Val Town API from within Val Town, a short-lived API token is automatically injected into your environment variables. These injected tokens are what provide authenticated access to Val Town Standard Library services.

All tokens are scoped to the permissions you’ve granted them.

Scopes

Val Town API tokens are scoped to read/write scopes for:

• val – vals
• user – user account details
• blob – blob storage
• sqlite – sqlite database
• email – ability to send emails

You can confiure the scopes on the API Tokens page or the settings page of your val.

The default scope for vals exclue val:write and user:write to limit potential damage from misconfiguration, vulnerable libraries, or account compromises. You can manually enable those scopes if you need them, but we advise extreme caution when doing so. Be sure to audit all your dependencies recursively for such vals.

API Token Lifecycles

API Tokens come with configurable expiration dates. We strongly recommend setting expiration dates for your tokens and rotating them regularly.

If you accidentally leak or misplace an API token, you can delete it on the API Tokens paage, immediately preventing any further access to your account from that token.

In rare cases where we detect a potential leak of your API Token, we’ll take proactive measures. We’ll automatically revoke the compromised token and promptly notify you via email.