Participants and Access

Understand how members, users, scopes, accounts, grants, and API keys determine who can do what, and from which account.

Four objects determine who can trade and which account they can use.

Term	Meaning
Member	The person or organization participating on the exchange.
Account	Holds balances and positions. A member can have more than one account.
User	A person or programmatic identity that authenticates to the exchange.
Grant	Gives a user permission to act on an account.

How Access Works

Two things decide what a request may do. A user’s scopes say what kind of action the user may take: trade, move funds, manage accounts, and so on. A user’s grants say which accounts those actions may touch. A user can have grants on multiple accounts, and an account can be shared by multiple users.

API keys belong to users. A key holds a subset of its user’s scopes and can be restricted to one account, but it cannot give the user access they do not already have. A key’s access cannot be widened after creation: revoke it and create another key with the required access. See Authentication for the scope vocabulary and key restrictions.

Users

User status	Meaning
`pending`	Activation is still running.
`active`	The user can authenticate.
`suspended`	The user cannot authenticate.

A user in any status can hold grants, but only an active user can use them.

Scopes are never granted by default. The exchange assigns the first user’s scopes during onboarding; after that, a user holding users:manage sets the scopes of the member’s other users under three rules:

Every scope the change adds or removes must be one the manager holds. A manager cannot hand out funds:transfer without having it, and cannot take it away either.
The user’s API keys shrink to the new scopes at the same moment. A key left with no scope is revoked.
The member’s last users:manage holder cannot remove that scope from themselves, so a member can never lock itself out.

A users:manage holder can also create, list, and revoke another user’s API keys, for members that do not want traders minting their own. Those keys are capped by their owner’s scopes and grants, not the manager’s.

Accounts

A member creates an account by name, using an interactive user session or an unrestricted API key with the accounts:manage scope — a key restricted to one account cannot create accounts. Setup is asynchronous: the account starts pending and becomes active when it can trade.

Account status	Meaning
`pending`	Setup is still running.
`active`	Setup is complete and the account can trade.
`failed`	Setup failed. This is not terminal: setup is retried.

Grants

Any user with a grant on an account can grant the member’s other users access to it. Granting access records the grant immediately; access is set up afterward, so the grant starts pending and becomes active when setup completes.

Grant status	Meaning
`pending`	Access is still being set up.
`active`	The grant is usable.
`failed`	Setup failed. This is not terminal: setup is retried, so keep polling.

Lists of orders, fills, and positions that cover more than one account include an account only after its setup and the setup of your access to it have both completed.

Revoking a grant ends access immediately: the revoked user’s next request against the account is rejected, including through an API key restricted to that account. Revocation is permanent; to restore access, create a new grant.