Authentication

We have a two-fold authentication framework to ensure that the caller of the API is known and that calls have not been tampered with en route.

How authentication works

OAuth 2.0

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 and a client secret that can be used to request access tokens via our OAuth2 endpoints.

Authentication scopes

The Upvest Investment API supports granular authentication scopes, thus improving security. You can restrict the permissions and data that is requested during authentication by specifying the scopes.

The following table lists available scopes:

Scope Permissions
accounts:read Read accounts and accounts groups.
accounts:admin Create/update/delete accounts and accounts groups.
webhooks:admin Create/update/delete webhooks.
webhooks:read Read webhooks.
orders:admin Create/update/delete orders.
orders:read Read orders.
users:admin Create/update/delete users.
users:read Read users.
checks:admin Create checks.
checks:read Read checks.
positions:read Read positions.
reference_accounts:admin Create/update/delete reference accounts.
reference:accounts:read Read reference accounts.
mandates:admin Create/update/delete mandates.
mandates:read Read mandates.
payments:admin Payments and withdrawal operations.
payments:read Payments and withdrawal read operations.
reports:read Read reports.
taxes:read Read tax residencies.
taxes:admin Modify tax residencies.
instruments:read Read instruments.
fees:admin Create and read fee operations.
fees:read Read fee operations.
portfolios:read Read portfolios.
portfolios:admin Modify portfolios.
reinvestments:read Read reinvestments.
reinvestments:admin Modify reinvestments.
valuations:read Read account valuations.
EXAMPLE

Request a users:read access token to read user data but not be able to change user data. Then request a users:admin access token to be able to onboard new users.

More on available permissions see here. Auth

Once the access token is returned, the token can be used in all requests for the specific required scopes using the standard authorization header as shown below:

Example header

Authorization: Bearer <access_token>

The use of client_credentials alone allows us to identify you and authorise your request. However, it does not protect against a man-in-the-middle attack, where the request can be maliciously modified. To mitigate this risk, there is an additional layer of public key infrastructure in the form of HTTP signatures.

HTTP signatures

OAuth 2.0 is only used to authenticate your client backend calling the Upvest API (i.e. to know who is the client calling the Upvest API). In addition, we also want to make sure that the call is actually coming from your backend and has not been tampered with along the way. For this we use HTTP message signatures

HTTP message signatures should be considered transparent and any request sent to the Investment API must be signed with the private key corresponding to the OAuth 2.0 client_id. If this is not the case, the request will be rejected.

Once HTTP signatures are in place, normal OAuth 2.0 flows can be used. To do this, get a scoped access token with client_id and client_secret and use the access token to call the Investment API.

Detailed instructions on how to calculate the signature can be found here.

Was this page helpful?