Overview of OAuth 2.0 within the Upvest Investment API

The Investment API uses opaque access tokens obtained using the OAuth 2.0 Client Credentials flow.

During the onboarding process, each client receives a client ID, a client secret, and a key ID which are required to request access tokens via our OAuth 2.0 endpoints.

Authentication is a three-step process:

1. Request an access token from the token endpoint, specifying the scopes you need. Access tokens expire within 1800 seconds (30 mins). When this occurs, you must request a new token.
2. Read the token response to extract the access token and its metadata.
3. Call the API with that token in the Authorization header until it expires, then request a new one.

Every request to Upvest, including the request to the token endpoint, must additionally be signed using HTTP message signatures. The client credentials identify and authorise you; the message signature protects the request against tampering in transit. Make sure you have set up request signing before you attempt to fetch a token.

Send a POST request to the token endpoint for your environment:

The request body must be application/x-www-form-urlencoded and contain the following fields:

The request must also carry the upvest-client-id header and the HTTP message signature headers (signature and signature-input).

curl --request POST 'https://sandbox.upvest.co/auth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'upvest-client-id: <your_client_id>' \
  --header 'signature: <generated_signature>' \
  --header 'signature-input: <generated_signature_input>' \
  --data-urlencode 'client_id=<your_client_id>' \
  --data-urlencode 'client_secret=<your_client_secret>' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=users:read users:admin'

See the HTTP message signatures page for how to generate the signature and signature-input headers.

A successful request returns a JSON body containing the token and its metadata:

{
  "access_token": "<access_token>",
  "expires_in": 86400,
  "token_type": "bearer",
  "scope": "users:read users:admin"
}

Send the token in the standard Authorization header on every API request, and continue to send upvest-client-id and your message-signature headers:

upvest-client-id: <your_client_id>
Authorization: Bearer <access_token>
signature: <generated_signature>
signature-input: <generated_signature_input>

The token remains valid for the number of seconds returned in expires_in. Reuse the same token across requests until it is close to expiry, then request a new one. Avoid fetching a new token for every call.

• Scope tokens to the task. Request only the scopes a given workflow needs. For example, use a users:read token for read-only access, and request a separate users:admin token only when you need to onboard or modify users.
• Cache and reuse tokens. Hold a token until shortly before expires_in elapses rather than requesting one per call, to reduce latency and load.
• Store your client secret securely. Treat the client secret like a password: keep it server-side, never embed it in client applications or commit it to source control.

The Upvest Investment API supports granular authentication scopes to improve security. By specifying scopes when you request a token, you restrict the permissions and data access that token grants.

Two distinct sets of scopes are relevant:

• Scopes granted to your client — the full set of scopes Upvest has enabled for you. Upvest provides this list when sending your API credentials during onboarding. You can only request scopes from this set.
• Scopes on a token — the subset of your granted scopes that you request in the scope field when fetching a particular token. A token only carries the permissions you explicitly request for it.

You must ensure that each token carries the scopes required by the endpoints you call with it. The required scopes for each endpoint are listed in the security details of that endpoint.

In the API reference: open the endpoint to view the required scopes. You can select View security details in the Security section to see scope details.

The Security window shows additional details, including optional scopes for the endpoint.

The following scopes are available in the Upvest Investment API. For the current required scopes of any specific endpoint, always check its security details in the API reference.

For more on how scopes map to permissions, see Permissions.

Scope errors include a status code to help you troubleshoot.

If you request a scope that has not been granted to your client, the token endpoint responds with status 401 and does not issue a token.

This happens when the scope field includes a scope that is outside the set Upvest enabled for you. Because the set of scopes granted to your client is configured on the Upvest side, you cannot change it yourself.

To resolve a 401:

• Compare the scopes in your request against the list of granted scopes Upvest sent you during onboarding, and remove any scope that is not on that list.
• If your integration needs a scope that has not been granted, contact the Upvest team to enable the required scopes.

If you call an endpoint with a token that does not include the scope that endpoint requires, the API responds with status 403.

This happens when the scope is available to your client but was not included in the scope field when you fetched the token. In other words, the permission exists for you, but this particular token does not carry it.

To resolve a 403:

• Check the endpoint's required scopes under View security details in the API reference.
• Request a new token whose scope field includes the required scope, then retry the request with that token.

Using client_credentials alone lets us identify and authorise you, but it does not protect against a man-in-the-middle attack, where a request could be maliciously modified in transit.

To mitigate this, Upvest requires an additional layer of public key infrastructure in the form of HTTP message signatures on every request, including the token request.