Skip to navigation
Core concepts

Concepts

The partner secret authenticates your server. The session token authenticates your app. Everything else in the API builds on these five concepts.

Partner

A partner is your company. Sinbad chooses the partner ID when it creates your account, for example atlas. You send it only if you also send the optional X-Partner-Id header.

Integration

An integration is one approved app or website under your partner account. It holds:

  • The exact browser origins allowed to call Sinbad, such as https://app.example.com.
  • The chain IDs your customers’ wallets may use.
  • Whether Sinbad trusts your email verification and your phone verification.
  • A publishable key, pk_…, which identifies the integration. It is not a password and cannot create a session.

For local development you may use http://localhost or http://127.0.0.1 with a port. Every other origin must use https.

Credential

A credential is the server secret, sk_…. Sinbad shows the plaintext once and stores only a hash. If you lose it, Sinbad issues a new one, and the old one can be retired or revoked.

A credential has full access to your partner’s APIs. It can create sessions and revoke a single session only for the integrations listed on it. The customer directory, revocation of all of a customer’s sessions, customer deletion and partner configuration apply across your whole partner. There are no permission scopes.

Your user and Sinbad’s user

IDCreated byMeaning
partnerUserIdYouYour stable ID for the customer. It is case-sensitive, 1 to 128 characters, with no leading or trailing spaces or control characters. Send it on every session request.
userIdSinbadSinbad’s ID for the same person, shaped like b2b_…. It does not change between sessions.
sessionIdSinbadThe ID of one session. It is also the token’s jti claim.

Session

A session proves that your server asked Sinbad to open access for one customer, on one integration, with one wallet and chain. A new session lasts 86,400 seconds (24 hours). Every request creates a new session, there is no refresh token, and session creation takes no idempotency key.

The first request for a customer must include their legal name, a verified email, a wallet address and a chain ID. Later requests can omit them. The wallet and chain are fixed after the first success, and changing either returns 409 CONFLICT. A wallet, email address or phone number must be unique among a partner’s active customers, across integrations. Customers of different partners are independent.