Skip to navigation
Customer setup

Create a session

A session proves that your server vouches for one customer on one integration, with one wallet and chain. Your server creates it with POST /v1/sessions, using the partner secret, and hands only the session token to the customer’s app.

First registration

For a customer’s first session, send integrationId, your partnerUserId, the customer’s fullName, a verified email address (email with emailVerified: true), and their registered walletAddress and chainId. You can also send preferredName, dateOfBirth, country, locale, a verified phone (with phoneVerified: true) and a partnerSessionId for your own correlation. The date of birth is your assertion, not KYC evidence from Sinbad. Use the first-registration example on the endpoint page for the exact shape.

A duplicate wallet, email address or phone number belonging to another active customer returns 409 CONFLICT.

Returning customer

For later sessions, send only the same integrationId and partnerUserId. Do not create a new identity to recover a session.

{ "integrationId": "integration_demo", "partnerUserId": "customer_demo" }

Confirm current access

A valid token signature does not prove that the session is still active, because signature checks cannot detect revocation. Call GET /v1/session to check current access, and read GET /v1/.well-known/jwks.json if you verify tokens yourself. See Authentication.

Things to know

  • Quotas. Session creation has per-partner and per-customer quotas. A 429 response includes Retry-After and details.retryAfter. See Limits and limitations.
  • Lifetime. A session lasts 86,400 seconds (24 hours). There is no refresh token. Create another session when you need one.
  • Server secrets only. The partner secret needs a server-to-server request without an Origin header. Browsers use only the customer’s session token.