Reference
Client Secrets
Short-lived, session-scoped tokens for redirecting users to the hosted verification flow.
Every session creates a client secret (prefixed cs...) alongside it. The client secret is safe to expose to the frontend — it authorizes a single user to complete one specific session.
For the end-to-end integration pattern (create session on backend, pass URL to frontend), see Authentication & Keys.
Properties
| Property | Type | Description |
|---|---|---|
secret | string | The client secret token, prefixed cs. |
url | string | Pre-built hosted verification URL including the secret. Redirect users here. |
createdAt | number | Unix millisecond timestamp when the secret was created. |
expireAt | number | Unix millisecond timestamp when the secret expires. Two hours from creation. |
Example
{
"secret": "csea61d44d88d345e1b91622820bb73100",
"url": "https://session.facesign.ai?cs=csea61d44d88d345e1b91622820bb73100",
"createdAt": 1761001508335,
"expireAt": 1761008708335
}Refreshing an expired secret
If a user doesn't complete verification within two hours, mint a new client secret for the same session:
const clientSecret = await client.session.createClientSecret({ sessionId })
// Redirect the user to clientSecret.urlThe underlying session state (status, report, flow) is preserved.
Security properties
- Single-session: each secret authorizes exactly one session. Cannot be reused or used to create new sessions.
- Short-lived: expires two hours after creation.
- URL-safe: designed for embedding in redirect URLs, iframes, and WebViews.
- Read-only: cannot read or modify sessions other than its own.
API keys must stay on the server. Client secrets are the only credential that should reach the browser.