The Val Town APIs accept Bearer Token authentication for full access to your Val Town account. You can use the schemes below to give more scoped access to run specific vals.
Val Town Authentication
Keep your Val Town API token extremely guarded because it conveys access to your entire account and all of its environment variables. Never expose this token on the client.
Val Town’s API uses Bearer Authentication, which means you pass an HTTP Header
Authorization: Bearer <token>.
If you don’t pass an authentication token, your code will be run as an anonymous user and only have access to public vals. For example, unauthenticated access to a private val will fail:
Authenticated use will have read access to the authenticated user’s private vals
and environment variables, write access to the authenticated user’s vals, and the ability to
send the authenticated user emails via
You can access your Val Town API tokens here.
If you want to experiment with calling the Val Town API from within Val Town (as is shown above), you should copy-and-paste one of your Val Town API tokens into your environment variables.
You can roll arbitrary authentication schemes in user space. For example, I find
it useful to simply supply a custom
auth header from my Clerk webhooks that I
check like a password against a value I store in my environment variables:
I call this value
clerkNonSensitive because this value doesn’t protect any
data. It merely makes it impossible for anyone to trigger this public API
endpoint without the password. The worst that could happen if this password
leaks is that our team temporarily gets spam discord messages. Then I could just
change the password to a new value. For more sensitive use-cases, you’ll want to
sign & possibly encrypt the conveyed data using standard authentication methods.
You can hide the code of a public API by wrapping a private Val in a public val.
Below I show
hiddenAPI which you can see and
call via API,
but you notice that it calls
@stevekrouse.hiddenAPIInternal which is private
and can’t be inspected.