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.
The Upvest Investment API supports granular authentication scopes, thus improving security. You can restrict the permissions and data access that is requested during fetching of the authentication token by specifying the scopes.
You can add only scopes which Upvest configured for your client. Upvest provides a complete list of your initially configured scopes when sending your API credentials.
You must ensure that your token has the required scopes for your API requests. You can find the required scopes specified in the security details of the API request in the API reference of our documentation.
Simply press the View security details in the Security section in the specific endpoint.
The Security window appears and shows the required scopes for the endpoint.
If you are missing scopes on the client, you will receive an error response with status 401 when creating the token. You must reach out to the Upvest team for further clarification or to update your configuration.
New functionalities and features may require new scopes. Refer to the API reference for details on the required scope for the endpoint.
If you are missing scopes on the token, you'll get an error response with status 403 on the request. To fix this error you must ensure to add the required scopes to the token while fetching it.
The following table lists available scopes:
| Scope | Permissions |
|---|---|
| Users, Account Management, and Taxes | |
accounts:read | Read accounts and accounts groups. |
accounts:admin | Create/update/delete accounts and accounts groups. |
checks:admin | Create and read user checks. |
checks:read | Read checks by user or by the check ID. |
users:admin | Create/update/delete users and user identifiers. |
users:read | Read users and user identifiers. |
| Taxes | |
taxes:admin | Modify tax residencies and create/modify tax exemptions. |
taxes:read | Read tax residencies. |
| Instruments and Prices | |
instruments:read | Read instruments. |
prices:read | Read instrument prices including latest price and OHLC prices. |
| Orders | |
orders:admin | Create/update/delete orders. |
orders:read | Read orders. |
| Investment Solutions | |
account_liquidations:admin | Trigger/read/cancel accounts liquidations. |
account_liquidations:read | Read accounts liquidations. |
portfolios:admin | Modify portfolios including allocations, configurations, and rebalancing. |
portfolios:read | Read portfolios. |
savings_plan:admin | Create/read savings plans. |
savings_plan:read | Read savings plans. |
| Payments | |
payments:admin | Payments and withdrawal operations including direct debits and withdraws. |
payments:read | Payments and withdrawal read operations. |
mandates:admin | Create/update/delete mandates. |
mandates:read | Read mandates. |
reference_accounts:admin | Create/update/delete reference accounts. |
reference_accounts:read | Read reference accounts. |
topups:admin | Top-ups operations. |
topups:read | Top-ups read operations. |
credit_fundings:read | Read credit fundings details. |
| Balances | |
positions:read | Read positions and cash balances. |
valuations:read | Read account valuations. |
account_returns:read | Read accounts returns. |
virtual_cash_balances:admin | Increase and decrease virtual cash balances. |
| Fees | |
fees:admin | Create and read fee operations. |
fees:read | Read fee operations. |
| Reporting | |
files:read | Read files metadata. |
reports:admin | Create reports. |
reports:read | Read reports. |
transactions:read | Read cash and securities transactions. |
| Security transfers | |
security_transfers:admin | Create and read securities transfers. |
security_transfers:read | Read securities transfers. |
| Webhooks | |
webhooks:admin | Create/update/delete webhooks. |
webhooks:read | Read webhooks. |
| Tests | |
tests:admin | Trigger a bank transaction for testing purposes. |
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.
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:
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 message signatures.