Skip to main content

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.

Use the SDK if you can

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​

PropertyValue
AlgorithmES256
Issuer (iss)tc-hub
Audience (aud)tc:app:<project> on a self-hosted installation, tc:app:<tenant>:<project> on vastframe cloud
Lifetime5 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​

ClaimMeaning
oidThe person's stable id (the Entra object id when you sign in with Entra)
name, emailDisplay name and email
department, job_titleFrom the directory, or null
groupsGroup display names (handy for app code)
group_idsGroup ids (use these for decisions; names can change)
rolesThe person's app roles in this project
project, deploymentThe project and deployment the token was minted for
tidThe organization (tenant slug) the token was minted in
roleAlways tc_user: the database role the project's Data API switches to, so row-level security applies

Where to get the keys​

CallerJWKS URL
Server code in a deployed app$TC_JWKS_URL (injected by the platform)
Anything on an app originhttps://<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, ... }
}
Always check the audience

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.

note

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:

EndpointWhat it does
GET /_tc/auth/meReturns { user, project, token_expires_in } for the signed-in user, or 401 with a login_url
GET /_tc/auth/login?rd=/pathStarts sign-in and returns to /path
/_tc/auth/logoutSigns 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-User header 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.
Was this page helpful?