> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getsinbad.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getsinbad.com/_mcp/server.

# Concepts

> The five names you need: partner, integration, credential, user and session.

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

| ID              | Created by | Meaning                                                                                                                                                                 |
| --------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `partnerUserId` | You        | Your 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. |
| `userId`        | Sinbad     | Sinbad's ID for the same person, shaped like `b2b_…`. It does not change between sessions.                                                                              |
| `sessionId`     | Sinbad     | The 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.