Client Secrets

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

clientSecret

{
  "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.url

The 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.

Next Steps

Authentication & Keys

Full integration pattern and security rules.

Create Session

The endpoint that returns a client secret.

Create Client Secret

Mint a new secret for an existing session.

Getting started

Endpoints

Webhooks

Properties

Example

Refreshing an expired secret

Security properties

Next Steps

Authentication & Keys

Create Session

Create Client Secret

​Properties

​Example

​Refreshing an expired secret

​Security properties

​Next Steps

Authentication & Keys

Create Session

Create Client Secret

Properties

Example

Refreshing an expired secret

Security properties

Next Steps