Restricted App Access
A val has two independent access settings. Changing one does not change the other:
- Code (: / / ) — who can read the source on val.town.
- App access (: / ) — who can call the val's HTTP endpoints.
A val can have private code and a wide-open endpoint, or public code and a locked-down endpoint.
's
field only moves the first one; app access is changed with
.
Restricted app access is available to organizations that have the feature enabled. Vals created in such an org may default to
— always read
off a
,
,
, or
response rather than assuming a new val's URL is open.
Is this the right tool?
Two different things both sound like "make my app require a login":
- Restricted app access (this skill) gates the endpoint at the platform edge, before your code runs. Requests from people without access never reach the val. You write no auth code. Access is granted to whole organizations, not to individuals.
- (see the skill) runs inside your val: you wrap your handler, and anyone with a Val Town account can log in. You control the session and can build per-user features.
Pick restricted access for an internal tool that only your team should reach. Pick
when any Val Town user may sign in and the app needs its own notion of a logged-in user.
Don't stack them by accident. Adding
to an already-restricted val means the visitor authenticates twice — once at the gate, once in your code. If a restricted val needs to know
who is viewing, use the identity header below instead of adding OAuth.
Who gets through
Access is granted to organizations, not individual people. A viewer gets in when the val has a grant to an org and that viewer is a member of it. Removing either one revokes access on the very next request — nothing is cached for the length of a session.
Grants come from:
- Direct grants — grants an org, shows current grants, revokes one.
- Domain rules — a val can admit everyone with an email address at a given domain. These appear in alongside direct grants.
- Invitations — someone outside a granted org can be invited by email and gains access when they accept.
- Bypass tokens — a project-scoped secret for machines; see below.
What everyone else sees
An unauthenticated request does
not reach the val. The platform answers with a
redirect to a Val Town login or authorization page. This is the single most common source of confusion when debugging a restricted val:
- reports a redirect it won't follow.
- shows a to instead of your response.
- An API client gets HTML from a login page where it expected JSON.
- A visitor without access who is logged in gets a explaining they need access to their organization.
None of these mean the val's code is broken. Check
first — if it's
, the gate is doing its job. Make the val public with
, grant the caller's org, or use a bypass token.
Automation and webhooks
Machines can't complete a login redirect, so a restricted val that receives webhooks (Stripe, GitHub, a cron job in another val) needs a bypass token — a secret scoped to that one val.
Create it with
; the secret is shown once and cannot be retrieved again. Manage tokens with
and
.
Present it either way:
ts
// Header (preferred — keeps the secret out of logs and referrers)
await fetch(url, { headers: { "X-Val-Town-Access": Deno.env.get("MY_BYPASS_TOKEN")! } });
// Query param (for services that only accept a URL, e.g. some webhook configs)
await fetch(`${url}?val_town_access=${Deno.env.get("MY_BYPASS_TOKEN")}`);
The platform strips the header and the query param before your handler runs, so your code never sees them. A bypass-token request carries no viewer identity — it is an anonymous machine caller.
Identifying the viewer
For a human viewer who came in through the gate, the platform forwards a short-lived signed
header. It is not the identity itself — exchange it for the viewer's profile using the val's own API token, which Val Town injects as the
environment variable:
ts
const IDENTITY_HEADER = "X-Val-Town-User";
async function getViewer(req: Request) {
const signed = req.headers.get(IDENTITY_HEADER);
if (!signed) return null;
const res = await fetch("https://api.val.town/v3/val/viewer", {
headers: {
Authorization: `Bearer ${Deno.env.get("valtown")}`,
[IDENTITY_HEADER]: signed,
},
});
if (!res.ok) return null;
// { id, username, type, bio, profileImageUrl, url, links }
return await res.json();
}
Rules that matter:
- Always treat the viewer as optional. There is none on a public val or a bypass-token request. Never -assert it or index into a null result.
- Resolve it server-side, on each request. The credential is short-lived and tied to your val — don't persist it, hand it to the browser, or attempt the lookup from client-side code.
- Only public profile fields come back — handle, bio, avatar, profile URL. No email address, no billing tier. Don't build a val that depends on those.
The transport above (
plus the
exchange) is how this works today and may change; the three rules hold regardless.
Managing app access
| Task | Tool |
|---|
| Check the current setting | ( field) |
| Make an endpoint public or restricted | |
| See who has access | |
| Grant / revoke an org | / |
| Create / list / revoke automation secrets | / / |
Restricted vals can only be iframed by val.town, so an embed of one on an external site will be blocked by the browser regardless of who's logged in.