Participants and Access

Understand how members, users, accounts, grants, and API keys determine who can access and trade from each account.

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

How Access Works

A user can have access to multiple accounts, and an account can be shared by multiple users. Each user-to-account relationship is a grant.

API keys belong to users. A key can be restricted to one account, but it cannot give the user access they do not already have.

See Authentication for API key scopes and account restrictions.

Create an Account

POST /portfolio/accounts starts asynchronous account setup.

• The asynchronous 202 Accepted response body contains the newly created account’s id, name, and status; its initial status is pending.
• The request body contains the account’s human-readable name.
• The API key used for this operation must be unrestricted and have the trade scope.

Poll GET /portfolio/accounts with the same authenticated credential until the account’s status changes to active.

See Create an Account for the request and response.

Manage Account Access

Any user with a grant on an account can manage which of the member’s users can reach it. An API key used to view or change an account’s grants must be unrestricted and have the grants:manage scope.

• GET /users lists the member’s users — the identities a grant can authorize — each with its access status. It requires only the read scope.
• GET /portfolio/accounts/{account_id}/grants lists who holds access to an account, with each grant’s status.
• POST /portfolio/accounts/{account_id}/grants grants one of the member’s users access. UDX records the grant immediately; it starts pending while exchange access is set up, so poll the account’s grants until the new grant is active. A grant reports failed when exchange setup fails.
• DELETE /portfolio/accounts/{account_id}/grants/{grant_id} revokes a grant. Access ends immediately: the revoked user’s next request against the account is refused, including through an API key restricted to that account. Revocation is permanent; to restore access, create a new grant.

Any of the member’s users can be granted access, but a user whose status is not active cannot authenticate, so their grant becomes usable only once UDX activates them. See Grant Account Access and Revoke a Grant for requests and responses.