Skip to main content

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/me on your own origin.
  • Server: the Edge adds an X-TC-User header to every request: a JWT signed by the platform (ES256, issuer tc-hub, audience tc:app:<project>), valid for 5 minutes. tc.auth.user(req) verifies it against the platform's keys.
warning

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>
ParameterTypeDescription
reqRequestLikeServer 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:

FieldTypeDescription
idstringThe person's directory object id (Entra oid). Same value as tc.user_id() in SQL.
namestringDisplay name
emailstringEmail
departmentstring | nullDepartment from the directory
jobTitlestring | nullJob title
groupsstring[]Group display names (transitive)
groupIdsstring[]Group object ids
rolesstring[]App roles in this project (set by the owner under Access → App roles)
projectstring | nullThe project name the token was minted for
hasRole(role)booleanSame semantics as tc.has_role() in SQL
inGroup(group)booleanMatches a group name or id; same as tc.in_group() in SQL

Errors

CodeWhen
UNAUTHENTICATEDBrowser: the session expired. Server: the request has no X-TC-User header (for example, you're running outside the platform).
NO_ACCESSBrowser: the person isn't allowed to open the app. The fix names the owner to ask.
AUTH_UNAVAILABLEBrowser: the sign-in service answered with an unexpected status.
BAD_IDENTITYServer: the token didn't verify (expired, wrong audience, forged).
NO_REQUESTServer: no request was passed and you're not inside tc.middleware().
NOT_CONFIGUREDServer: TC_JWKS_URL isn't set.

Example

server.js
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
ParameterTypeDescription
returnTostringPath 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 helperReturns
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
Was this page helpful?