Verify the user's identity
Apps on vastframe never run their own sign-in. When a request passes the Edge's access check, the Edge forwards the signed-in user in the X-TC-User header as a short-lived JSON Web Token signed by the Hub. Your server reads it, verifies it, and knows who is calling.
tc.auth.user(req) (JavaScript) and tc.auth.user(request) (Python) verify the header for you. Verify by hand only if you aren't using the SDK. See the SDK reference.
Token format
| Property | Value |
|---|---|
| Algorithm | ES256 |
Issuer (iss) | tc-hub |
Audience (aud) | tc:app:<project> on a self-hosted installation, tc:app:<tenant>:<project> on vastframe cloud |
| Lifetime | 5 minutes by default. The Edge reuses a token for at most a few seconds (its decision cache), so treat every token as short-lived. |
Key id (kid) | Matches a key in the Hub's JWKS |
Claims
| Claim | Meaning |
|---|---|
oid | The person's stable id (the Entra object id when you sign in with Entra) |
name, email | Display name and email |
department, job_title | From the directory, or null |
groups | Group display names (handy for app code) |
group_ids | Group ids (use these for decisions; names can change) |
roles | The person's app roles in this project |
project, deployment | The project and deployment the token was minted for |
tid | The organization (tenant slug) the token was minted in |
role | Always tc_user: the database role the project's Data API switches to, so row-level security applies |
Where to get the keys
| Caller | JWKS URL |
|---|---|
| Server code in a deployed app | $TC_JWKS_URL (injected by the platform) |
| Anything on an app origin | https://<app>.<your-domain>/_tc/auth/jwks.json |
Cache the key set for a few minutes and refetch when you see an unknown kid.
Verify by hand
Check all four: the signature against the JWKS key with the token's kid, the issuer, the audience for your project, and the expiry.
import { createRemoteJWKSet, jwtVerify } from 'jose';
const jwks = createRemoteJWKSet(new URL(process.env.TC_JWKS_URL));
export async function currentUser(req) {
const token = req.headers['x-tc-user'];
if (!token) throw new Error('No X-TC-User header');
const { payload } = await jwtVerify(token, jwks, {
issuer: 'tc-hub',
audience: `tc:app:${process.env.TC_PROJECT}`, // tc:app:<tenant>:<project> on vastframe cloud
algorithms: ['ES256'],
});
return payload; // { oid, name, email, groups, roles, ... }
}
Tokens for different apps share the same signing keys. The audience is what stops a token minted for one app from being replayed against another. The Hub's own tokens (tc:hub) and scheduled-job tokens (tc:gateway) use different audiences for the same reason.
The platform injects the project name as TC_PROJECT and the JWKS URL as TC_JWKS_URL. The examples/whoami app in the repository shows a dependency-free verifier using only node:crypto.
In the browser
Front-end code doesn't see the header. Call these endpoints on your app's own origin instead:
| Endpoint | What it does |
|---|---|
GET /_tc/auth/me | Returns { user, project, token_expires_in } for the signed-in user, or 401 with a login_url |
GET /_tc/auth/login?rd=/path | Starts sign-in and returns to /path |
/_tc/auth/logout | Signs out of every app in the organization |
Everything under /_tc/ is reserved for the platform.
Why apps can trust the header
- The Edge removes any
X-TC-Userheader sent by the browser before it adds its own, so a client can't forge one. - The token is signed by the Hub with a key kept in the Hub database (Key Vault is planned). Apps only get the public keys.
- Tokens are bound to one project (audience) and expire after 5 minutes.
- Requests without a valid session never reach your app: browsers are redirected to sign-in, API clients get
401.