# new Auth(serviceKey)
Parameters:
| Name | Type | Description |
|---|---|---|
serviceKey |
ServiceKey
|
Example
// 1. Start the login redirect
const url = sdk.Auth().beginFlow({ redirectUri: 'https://myapp.com/callback' })
res.redirect(url)
// 2. Exchange the code after the redirect
const { idToken, user } = await sdk.Auth().completeFlow(code, 'https://myapp.com/callback')
// 3. Verify a token from an incoming request
const payload = await sdk.Auth().verify(idToken)Methods
# beginFlow(options) → {string}
Constructs the authorization URL to redirect the user to for login.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
options |
Object
|
|||
redirectUri |
string
|
URI the authorization server redirects to after login. |
||
state |
string
|
<optional> |
Optional opaque value forwarded in the redirect for CSRF protection. |
|
scope |
string
|
<optional> |
'openid profile email' | Space-separated list of requested scopes. |
The full authorization URL to redirect the user to.
string
Example
const url = sdk.Auth().beginFlow({
redirectUri: 'https://myapp.com/callback',
state: crypto.randomUUID()
})
res.redirect(url)# clearExchangeCache(sub)
Removes all cached exchanged tokens for a given user subject.
Call this on logout so the next asUser call performs a fresh token exchange
rather than returning a stale cached token.
Parameters:
| Name | Type | Description |
|---|---|---|
sub |
string
|
The user's |
Example
sdk.Auth().clearExchangeCache(session.user.sub)
session.destroy()# async completeFlow(code, redirectUri) → {Promise.<FlowResult>}
Exchanges an authorization code for tokens and returns the ID token and decoded user claims.
Call this in your OAuth callback handler after the authorization server redirects back
with a code query parameter.
Parameters:
| Name | Type | Description |
|---|---|---|
code |
string
|
The authorization code from the query string. |
redirectUri |
string
|
Must match the URI used in |
auth/complete-flow-failed – token exchange returned a non-OK status.
Error
auth/complete-flow-no-token – token response contained no usable token.
Error
Promise.<FlowResult>
Example
const { idToken, user } = await sdk.Auth().completeFlow(req.query.code, REDIRECT_URI)
// store idToken in session, use user.sub / user.email / user.tenantId# async exchangeToken(idToken) → {Promise.<string>}
Exchanges a user's OIDC ID token for a Scenid service access token.
The resulting token is cached per user+client until 60 seconds before it expires.
This method is called automatically by sdk.asUser(idToken) — you rarely need to
call it directly.
Parameters:
| Name | Type | Description |
|---|---|---|
idToken |
string
|
The OIDC ID token obtained from |
auth/exchange-failed – token exchange returned a non-OK status.
Error
A service-scoped access token.
Promise.<string>
# async getServiceToken() → {Promise.<string>}
Acquires a machine-to-machine service token using the client credentials grant.
The token is cached until 60 seconds before expiry. This method is called
automatically by sdk.asAdmin() — you rarely need to call it directly.
A service-scoped access token.
Promise.<string>
# middleware() → {function}
Returns an Express middleware that verifies an incoming Bearer token and
populates req.user (user tokens) or req.serviceClient (service tokens).
The JWKS used for verification is cached for one hour — no per-request
call to the auth service. Soft middleware: always calls next(), even when
no token is present or verification fails. Use gate functions to enforce access.
Express async (req, res, next) middleware.
function
Example
app.use(sdk.Auth().middleware())
app.get('/protected', async (req, res) => {
const user = await checkIsUser(req)
res.json({ sub: user.sub })
})# async refreshFlow(refreshToken) → {Promise.<FlowResult>}
Exchanges a refresh token for a new ID token.
Parameters:
| Name | Type | Description |
|---|---|---|
refreshToken |
string
|
The refresh token obtained from |
auth/refresh-flow-failed – token refresh returned a non-OK status.
Error
auth/refresh-flow-no-token – token response contained no usable token.
Error
Promise.<FlowResult>
# async verify(idToken) → {Promise.<Object>}
Verifies an ID token's issuer and expiry against the authorization server's JWKS.
The JWKS is fetched once and cached for one hour. Use this in server-side middleware
to confirm an incoming token was issued by your Scenid tenant before passing it to
sdk.asUser(idToken).
Note: currently validates issuer and expiry only — signature verification is not yet implemented.
Parameters:
| Name | Type | Description |
|---|---|---|
idToken |
string
|
The raw ID token to verify. |
auth/jwks-key-not-found – no matching key in JWKS for the token's kid.
Error
auth/invalid-issuer – iss claim does not match the configured issuer.
Error
auth/token-expired – token has passed its exp timestamp.
Error
auth/invalid-token-format – token could not be decoded.
Error
The decoded JWT payload (claims).
Promise.<Object>
Example
// Express middleware
const payload = await sdk.Auth().verify(req.headers.authorization?.split(' ')[1])
req.user = payload