A partner (such as a market maker or token issuer) signs in to act for an organization, never as a trader. Every authorization check runs on the server against the organization bound to your session or organization key.

Sign in and sessions

Exchange a verified partner identity once for a short-lived partner session bearer:
  1. Call POST /v2/partner/sessions with no Authorization header. Send { "idToken", "nonce" }, where idToken is the Google ID token from the partner sign-in screen and nonce is that screen’s raw nonce (Google receives base64url(SHA-256(raw nonce)) without padding). Where partner Cloudflare Access is configured, an empty body with the Cf-Access-Jwt-Assertion header is accepted instead.
  2. On success, POST /v2/partner/sessions answers 201 with an opaque token starting with edel_ps_, expiresAt, partnerUserId, lowercase email, and your active memberships (each with role and permissions). Only the SHA-256 hash of the token is stored, and the token is returned only in this response.
  3. Each identity token is single-use. Repeating an exchange with the same identity token answers 401 partner_identity_invalid. An uninvited address answers 403 partner_not_invited. Exchanges are limited to 20 per verified identity every 10 minutes (429 with Retry-After).
  4. A session expires 1 hour after its last accepted use, and at most 12 hours after creation. Each accepted request slides the idle deadline forward within that 12-hour limit.
  5. Send Authorization: Bearer <token> on partner and organization routes. Each partner user may send up to 120 requests per minute on the organization routes (429 with Retry-After). The organization list and market analytics share a second budget of the same size, and sign out has a third. Each budget is counted per API instance.
List your active organization memberships with GET /v2/partner/organizations. This route accepts a partner session only (edel_ps_...); an organization key answers 403 partner_session_required. Suspended organizations are omitted. Sign out at any time with DELETE /v2/partner/sessions/current. It revokes the bearer session immediately and answers 204.

Organizations, members, roles, and permissions

Read an organization with GET /v2/organizations/:organizationId. Both a partner session (edel_ps_...) and an organization key (edel_ok_..., up to 120 requests per minute per key, counted per API instance) may read the organization they belong to. Make an organization key on the Keys page of the partner dashboard; it needs members_keys write. Every member has one role (owner, admin, member) and holds one level (none, read, write) for each of the five permission groups (sub_accounts, trading_spot, trading_perps, listings_deposits, members_keys): write always includes read on the same group.
  • List members: Call GET /v2/organizations/:organizationId/members. It requires members_keys read, so owner, admin, and a member with members_keys read or write can list members. Organization keys never hold members_keys and are refused.
  • Set member permissions: Call PATCH /v2/organizations/:organizationId/members/:memberId/permissions with a partner session (edel_ps_...) and members_keys write. Send all five groups in permissions. A member with members_keys write cannot grant a level above their own. Organization keys answer 403 organization_role_required. The route can also answer:
    • 403 organization_owner_protected: an admin or a member acts on the owner. Only the owner changes the owner’s levels.
    • 409 organization_member_role_fixed: the target is an owner or an admin, whose role already holds write on all groups.
    • 404 organization_member_not_found: no member with this ID in this organization.
    • 409 organization_member_changed: the member changed since you read it. Read it again, then retry.

Named refusals

Authorization refusals on organization routes use closed error codes: Authentication and feature-flag checks fail with explicit codes too:
  • Missing or wrong bearer kind: 401 or 403 partner_session_required on session-only routes, or 401 organization_key_required on key-only or unauthenticated calls.
  • Rejected session bearer: 401 partner_session_invalid, partner_session_expired, or partner_session_revoked.
  • Rejected organization key: 401 organization_key_malformed, organization_key_unknown, or organization_key_revoked.
  • Disabled feature: 403 feature_disabled with featureFlag naming the disabled gate.

Invitations

Invitations require a partner session (edel_ps_...) with members_keys write. Organization keys answer 403 partner_session_required.
  1. Create: Call POST /v2/organizations/:organizationId/invitations with email, role (admin or member), and, for a member invitation, all five permissions groups (admin invitations omit permissions). An owner or admin can invite an admin or a member with any levels; a member with members_keys write can invite only a member and only within their own levels. Invitations expire after 7 days by default. Existing members answer 409 organization_member_exists; duplicate open invitations answer 409 organization_invitation_open_exists.
  2. List: Call GET /v2/organizations/:organizationId/invitations to read open invitations, oldest first. Accepted, withdrawn, and expired invitations are omitted.
  3. Withdraw: Call POST /v2/organizations/:organizationId/invitations/:invitationId/withdraw with no body to cancel an open invitation. You cannot withdraw an owner invitation (403 organization_role_required), and a member can withdraw only a member invitation within their own levels. Unknown or other-organization invitations answer 404 organization_invitation_not_found; invitations already accepted, withdrawn, or expired answer 409 organization_invitation_not_open.
  4. Accept at the next sign-in: There is no separate accept route. Each sign-in via POST /v2/partner/sessions accepts the open invitations for the verified email into memberships with the invited role and permissions. A partner user invited to another organization gets that membership at their next sign-in, not at once.

Listing requests and the listing deposit

Listing routes accept either a partner session (edel_ps_...) or an organization key (edel_ok_...). Reads require listings_deposits read; mutations require listings_deposits write.
  1. Create a listing request: Call POST /v2/organizations/:organizationId/listing-requests with the spot token and market specification (instrumentAdmin, instrumentId, code, name, decimals, logoUrl, category, quoteAsset, tick/lot/price/quantity limits, listingPriceAtoms, makerReferencePriceAtoms, and noSecurityClaim: true). You may include an optional depositClaim (amount, sentAt, transactionReference) as a statement only; it never counts as a credit. Returns 201 in status pending. Limited to 10 requests per hour per organization, counted per API instance (429 with Retry-After).
  2. List requests: Call GET /v2/organizations/:organizationId/listing-requests to read your organization’s requests, newest first.
  3. Replace a logo: Call PUT /v2/organizations/:organizationId/listing-requests/:requestId/logo with logoUrl and reason. Returns state: "applied" while pending or before logo copy, or state: "waiting_operator" once the venue holds the logo.
  4. Read deposit instructions and state: Call GET /v2/organizations/:organizationId/listing-requests/:requestId/deposit. The response returns instructions (custodyParty, instrumentAdmin, instrumentId, decimals, amountNeeded, amountNeededAtoms, amountNeededSource, and reference { key, value }) plus state (waiting, partial, offered, confirmed). By default, amountNeeded covers 2 makers at 14 levels per side with the smallest valid order plus a 20% buffer, unless an operator sets a request minimum. Only a Canton transfer to custodyParty of the exact amountNeeded counts. The transfer must carry the metadata entry whose key is reference.key and whose value is reference.value.
  5. Confirm the deposit: After sending the Canton transfer, call POST /v2/organizations/:organizationId/listing-requests/:requestId/deposit/confirm with no body. When the venue accepts a matching pending transfer, it answers 200 with depositConfirmedAt set. If no matching transfer is ready, it answers 409 listing_request_deposit_not_confirmed. If a transfer is present while waiting on registrar or operator action, it answers 409 listing_request_deposit_accept_pending (do not resend the transfer). A decided request answers 409 listing_request_deposit_closed. Both deposit routes answer 503 canton_offline when the settlement ledger is unreachable.

Market analytics

Call GET /v2/organizations/:organizationId/market-analytics with a partner session (edel_ps_...) and listings_deposits read. Organization keys answer 403 partner_session_required. The response returns organizationId, timestamp, and markets: an array with one row per spot market created from your organization’s approved listing requests (marketId, symbol matching GET /v2/markets/{symbol}/stats, quote, and windows 24h, 7d, and all). The 24h and 7d windows report trades, quoteVolume, and fees as decimal strings in quote. The all window reports trades, while quoteVolume.all and fees.all are null and listed in unavailable.

Organization keys that trade

Not live yet. Organization keys cannot place or manage orders on trading routes today. This capability is planned in #5829.
Planned in #5829: a key stores its own level per permission group, still never more than its maker holds.

Per-company rate limit

Not live yet. Today, partner routes enforce only the per-user, per-key, and per-organization listing limits described above.
Planned in #5829: organization keys that trade get one trading budget per organization, shared by all its keys. The 429 names the limiter and the limit, with Retry-After.

Sub-accounts

Not live yet. Organization sub-accounts are planned in #5727.
Sub-accounts for organizations are not live yet. The sub_accounts permission group is already present in the organization access model, and sub-account routes will use it when released.

Shared reference

Use the REST API reference for full request and response schemas.