Skip to navigation
API ReferenceSessions

Create a customer session

Create a customer session.

Credential: Partner secret

Before you call

  • A server-side partner secret for the owning partner. Do not send an Origin header.

Creates a 24-hour customer session. Call this from your server with your partner secret, and do not send an Origin header. integrationId and partnerUserId are required. Take partnerUserId from your own verified login.

A customer’s first request must also include fullName, a verified email address (email with emailVerified: true), walletAddress and chainId. Later requests can omit details that Sinbad already has. If you send changed contact details, they must be verified again. Creating another session never changes the customer’s wallet or chain.

A wallet, email address or optional phone number must be unique among your partner’s active customers, across integrations. Wallet and email comparisons ignore case, and phone numbers use E.164 format. A duplicate returns 409 CONFLICT. If your partner account setup is incomplete, registering a new customer or changing contact details can return 502 UPSTREAM_ERROR: contact Sinbad and quote the requestId. Existing customers can still get sessions, and deleting a customer still works.

Every successful request creates a new session. Sinbad limits session creation per partner and per customer. The defaults are 60 and 5 per minute, and Sinbad can configure different values at onboarding. Invalid credentials do not use quota, and only a session that is actually created does. A 429 RATE_LIMITED response includes Retry-After and error.details.retryAfter, in seconds. Cache the token until shortly before it expires.

Confirm with Sinbad that this endpoint is enabled in your environment.

Errors

StatusCodeWhat to do
400VALIDATION_ERRORCorrect the fields reported in details before retrying.
401UNAUTHENTICATEDCreate a new customer session or use a valid server credential.
403FORBIDDENCheck credential ownership, integration and the supplied Origin.
409CONFLICTRead the current state again before you prepare or retry.
429RATE_LIMITEDWait for Retry-After before retrying.
502UPSTREAM_ERRORRetry with backoff and quote requestId if it persists. For transaction reports, retry the same hash without sending another transaction.
503UPSTREAM_ERRORRetry with backoff; preserve the same idempotency key for a repeated mutation.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
integrationIdstringRequiredformat: "^[a-zA-Z0-9_-]{1,128}$"
partnerUserIdstringRequired1-128 characters

Case-sensitive; no leading/trailing whitespace or control characters.

fullNamestringOptional1-200 characters
preferredNamestringOptional1-200 characters
emailstringOptionalformat: "email"<=254 characters

Requires emailVerified=true; normalized to lowercase.

emailVerifiedbooleanOptional
Requires email in the same request.
phonestringOptionalformat: "^\+[1-9][0-9]{7,14}$"

Requires phoneVerified=true.

phoneVerifiedbooleanOptional
Requires phone in the same request.
walletAddressstringOptional

Nonzero EVM address; mixed-case checksum validated. Requires chainId. Stored lowercase, no smart-account or signer assumption.

chainIdintegerOptional>=1
Requires walletAddress and approved integration chain.
countrystringOptionalformat: "^[A-Z]{2}$"
dateOfBirthdateOptional

Valid past date; partner assertion, not KYC evidence.

localestringOptionalformat: "^[A-Za-z0-9-]+$"2-35 characters
partnerSessionIdstringOptional1-128 characters

Optional correlation; only its SHA-256 digest is audited. No replay prevention or idempotency.

Response

First or subsequent session; no refresh token

sessionTokenstring
sessionIdstring
expiresInenum
Allowed values:
expiresAtdatetime
userIdstring
kycStatusstring or null

Always null in auth-only phase. Future KYC adapter owns status reads.

isNewUserboolean

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
502
Bad Gateway Error
503
Service Unavailable Error