Auth and identity
Your app never handles sign-in. The Edge signs people in with your company identity provider and checks that they may open the app before the request reaches you. Your code just asks who it is.
- Browser:
tc.auth.user()calls/_tc/auth/meon your own origin. - Server: the Edge adds an
X-TC-Userheader to every request: a JWT signed by the platform (ES256, issuertc-hub, audiencetc:app:<project>), valid for 5 minutes.tc.auth.user(req)verifies it against the platform's keys.
Don't add login pages, OAuth libraries, MSAL, session cookies or JWT secrets. They aren't needed and they bypass the platform's access checks.
tc.auth.user()
Returns the signed-in user.
// Browser
tc.auth.user(): Promise<User>
// Server
tc.auth.user(req?: RequestLike): Promise<User>
| Parameter | Type | Description |
|---|---|---|
req | RequestLike | Server only. An Express/Node request, a Fetch Request, a Hono context, or the raw X-TC-User token. Optional inside tc.middleware(). |
Returns a User:
| Field | Type | Description |
|---|---|---|
id | string | The person's directory object id (Entra oid). Same value as tc.user_id() in SQL. |
name | string | Display name |
email | string | |
department | string | null | Department from the directory |
jobTitle | string | null | Job title |
groups | string[] | Group display names (transitive) |
groupIds | string[] | Group object ids |
roles | string[] | App roles in this project (set by the owner under Access → App roles) |
project | string | null | The project name the token was minted for |
hasRole(role) | boolean | Same semantics as tc.has_role() in SQL |
inGroup(group) | boolean | Matches a group name or id; same as tc.in_group() in SQL |
Errors
| Code | When |
|---|---|
UNAUTHENTICATED | Browser: the session expired. Server: the request has no X-TC-User header (for example, you're running outside the platform). |
NO_ACCESS | Browser: the person isn't allowed to open the app. The fix names the owner to ask. |
AUTH_UNAVAILABLE | Browser: the sign-in service answered with an unexpected status. |
BAD_IDENTITY | Server: the token didn't verify (expired, wrong audience, forged). |
NO_REQUEST | Server: no request was passed and you're not inside tc.middleware(). |
NOT_CONFIGURED | Server: TC_JWKS_URL isn't set. |
Example
import express from 'express'
import { tc } from '@tenantcloud/sdk'
const app = express()
app.get('/api/me', async (req, res) => {
const me = await tc.auth.user(req)
if (!me.hasRole('approver')) return res.status(403).json({ error: 'Approvers only' })
res.json(me)
})
app.listen(process.env.PORT ?? 8080)
tc.auth.token()
Returns the raw X-TC-User token so you can forward it to another service of the same app. Returns null in the browser.
tc.auth.token(req?: RequestLike): string | null
tc.auth.login()
Browser only. Sends the browser through company sign-in and back.
tc.auth.login(returnTo?: string): void
| Parameter | Type | Description |
|---|---|---|
returnTo | string | Path to return to. Default: the current page. |
tc.auth.logout()
Browser only. Signs the person out of every vastframe app (single sign-out).
tc.auth.logout(): void
Identity in SQL
The same identity is available inside the database, so row-level security can use it. See Database and the Data section.
| SQL helper | Returns |
|---|---|
tc.user_id() | The signed-in user's id |
tc.user_email(), tc.user_name(), tc.department() | Profile fields |
tc.has_role('approver') | Whether the user has that app role |
tc.in_group('Finance - FP&A') | Whether the user is in that group |