Sign in and sessions
Exchange a verified partner identity once for a short-lived partner session bearer:- Call
POST /v2/partner/sessionswith noAuthorizationheader. Send{ "idToken", "nonce" }, whereidTokenis the Google ID token from the partner sign-in screen andnonceis that screen’s raw nonce (Google receivesbase64url(SHA-256(raw nonce))without padding). Where partner Cloudflare Access is configured, an empty body with theCf-Access-Jwt-Assertionheader is accepted instead. - On success,
POST /v2/partner/sessionsanswers201with an opaquetokenstarting withedel_ps_,expiresAt,partnerUserId, lowercaseemail, and your activememberships(each withroleandpermissions). Only the SHA-256 hash of the token is stored, and the token is returned only in this response. - Each identity token is single-use. Repeating an exchange with the same identity token answers
401partner_identity_invalid. An uninvited address answers403partner_not_invited. Exchanges are limited to 20 per verified identity every 10 minutes (429withRetry-After). - 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.
- Send
Authorization: Bearer <token>on partner and organization routes. Each partner user may send up to 120 requests per minute on the organization routes (429withRetry-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.
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 withGET /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 requiresmembers_keysread, soowner,admin, and amemberwithmembers_keysreadorwritecan list members. Organization keys never holdmembers_keysand are refused. - Set member permissions: Call
PATCH /v2/organizations/:organizationId/members/:memberId/permissionswith a partner session (edel_ps_...) andmembers_keyswrite. Send all five groups inpermissions. Amemberwithmembers_keyswritecannot grant a level above their own. Organization keys answer403organization_role_required. The route can also answer:403organization_owner_protected: anadminor amemberacts on theowner. Only the owner changes the owner’s levels.409organization_member_role_fixed: the target is anowneror anadmin, whose role already holdswriteon all groups.404organization_member_not_found: no member with this ID in this organization.409organization_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:
401or403partner_session_requiredon session-only routes, or401organization_key_requiredon key-only or unauthenticated calls. - Rejected session bearer:
401partner_session_invalid,partner_session_expired, orpartner_session_revoked. - Rejected organization key:
401organization_key_malformed,organization_key_unknown, ororganization_key_revoked. - Disabled feature:
403feature_disabledwithfeatureFlagnaming the disabled gate.
Invitations
Invitations require a partner session (edel_ps_...) with members_keys write. Organization
keys answer 403 partner_session_required.
- Create: Call
POST /v2/organizations/:organizationId/invitationswithemail,role(adminormember), and, for amemberinvitation, all fivepermissionsgroups (admininvitations omitpermissions). Anowneroradmincan invite anadminor amemberwith any levels; amemberwithmembers_keyswritecan invite only amemberand only within their own levels. Invitations expire after 7 days by default. Existing members answer409organization_member_exists; duplicate open invitations answer409organization_invitation_open_exists. - List: Call
GET /v2/organizations/:organizationId/invitationsto read open invitations, oldest first. Accepted, withdrawn, and expired invitations are omitted. - Withdraw: Call
POST /v2/organizations/:organizationId/invitations/:invitationId/withdrawwith no body to cancel an open invitation. You cannot withdraw an owner invitation (403organization_role_required), and amembercan withdraw only amemberinvitation within their own levels. Unknown or other-organization invitations answer404organization_invitation_not_found; invitations already accepted, withdrawn, or expired answer409organization_invitation_not_open. - Accept at the next sign-in: There is no separate accept route. Each sign-in via
POST /v2/partner/sessionsaccepts 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.
- Create a listing request: Call
POST /v2/organizations/:organizationId/listing-requestswith the spot token and market specification (instrumentAdmin,instrumentId,code,name,decimals,logoUrl,category,quoteAsset, tick/lot/price/quantity limits,listingPriceAtoms,makerReferencePriceAtoms, andnoSecurityClaim: true). You may include an optionaldepositClaim(amount,sentAt,transactionReference) as a statement only; it never counts as a credit. Returns201in statuspending. Limited to 10 requests per hour per organization, counted per API instance (429withRetry-After). - List requests: Call
GET /v2/organizations/:organizationId/listing-requeststo read your organization’s requests, newest first. - Replace a logo: Call
PUT /v2/organizations/:organizationId/listing-requests/:requestId/logowithlogoUrlandreason. Returnsstate: "applied"while pending or before logo copy, orstate: "waiting_operator"once the venue holds the logo. - Read deposit instructions and state: Call
GET /v2/organizations/:organizationId/listing-requests/:requestId/deposit. The response returnsinstructions(custodyParty,instrumentAdmin,instrumentId,decimals,amountNeeded,amountNeededAtoms,amountNeededSource, andreference{ key, value }) plusstate(waiting,partial,offered,confirmed). By default,amountNeededcovers 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 tocustodyPartyof the exactamountNeededcounts. The transfer must carry the metadata entry whose key isreference.keyand whose value isreference.value. - Confirm the deposit: After sending the Canton transfer, call
POST /v2/organizations/:organizationId/listing-requests/:requestId/deposit/confirmwith no body. When the venue accepts a matching pending transfer, it answers200withdepositConfirmedAtset. If no matching transfer is ready, it answers409listing_request_deposit_not_confirmed. If a transfer is present while waiting on registrar or operator action, it answers409listing_request_deposit_accept_pending(do not resend the transfer). A decided request answers409listing_request_deposit_closed. Both deposit routes answer503canton_offlinewhen the settlement ledger is unreachable.
Market analytics
CallGET /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
Planned in#5829: a key stores its own level per permission group, still never more than its
maker holds.
Per-company rate limit
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
Sub-accounts for organizations are not live yet. Thesub_accounts permission group is already
present in the organization access model, and sub-account routes will use it when released.