Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.uphold.com/llms.txt

Use this file to discover all available pages before exploring further.

All requests must be authenticated or they will be rejected with a 401 Unauthorized status code.

​
OAuth2

The REST APIs use the industry standard OAuth2 protocol for authentication. It’s a well defined and widely used specification for token-based authentication and authorization.

​
Grant types

Because the REST APIs are meant to be consumed by businesses, the supported grant type is client credentials. For this grant, you need to provide a valid client ID and client secret to create access tokens. To obtain an access token, you may call the Request OAuth2 token endpoint. You can then use access tokens to authenticate subsequent requests by adding the Authorization: Bearer {accessToken} HTTP header.
You can manage your clients in Enterprise Portal. Please note that client secrets act like passwords, so be sure to keep them secure!

​
Subjects

Calls to the REST API endpoints are always contextualized with a subject. A subject represents the actor performing the action, which can be one of the following:
  • client: The OAuth2 client itself, used for operations that don’t require user context
  • user:individual: An individual user within an organization
  • user:business: A business user within an organization
Depending on your client configuration, the client’s tokens may be able to target different subjects:
  • Organization-wide clients default to the client subject but can act on behalf of any user within an organization, provided they have the core.users:act-on-behalf-of scope. Add the X-On-Behalf-Of: user {userId} HTTP header to the request, where {userId} is the ID of the user you want to target.
  • Single-user clients are associated with a specific user within the organization and can only perform actions on behalf of that user. No additional header is required for these clients. However, you may optionally include the X-On-Behalf-Of: user {userId} HTTP header, but the {userId} must match the user associated with the client.

​
Scopes

Clients are associated with a set of scopes that define the permissions of tokens. This allows you to create as many clients as needed, each with a different set of permissions based on your requirements. If you attempt to call an endpoint that requires certain scopes, but the token you are using doesn’t have them, you will receive a 403 Forbidden status code.

​
API keys

API keys are another widely used way to authenticate requests, but they are not supported at this time. If you have a use case that requires API keys, please reach out to your Account Manager.

​
User blocked

If a user is internally blocked, every request to non GET endpoints will fail with 409 HTTP status code and the following body: 
{
  "code": "operation-not-allowed",
  "message": "The current status of the user does not allow calling this endpoint",
  "reasons": ["user-blocked"]
}