Skip to main content

​
Authentication

All API requests require an authorization header with a bearer token. An access token can be retrieved from our authorization server using the OAuth2 client credentials flow. If you would like to use our API, please contact us at [email protected] and we will issue you a client_id and client_secret.

​
Testing Connectivity

To test connectivity, you can use one of the following examples below which target our Sandbox environment. You will need to replace <client-id> and <client-secret> with the credentials you were given. 
fetch("<auth-endpoint-url>", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
    "grant_type": "client_credentials",
    "audience": "<audience>",
    "client_id": "<client-id>",
    "client_secret": "<client-secret>"
  })
})
  .then(response => {
    console.log(response);
  })
  .catch(err => {
    console.error(err);
  });

​
Using the Access Token

Once you receive an access token from the authorization server, include it in the Authorization header of your API requests: 
Authorization: Bearer <access_token>
Access tokens expire after a set period. When a token expires, you’ll need to request a new one using the same OAuth2 client credentials flow.

​
User Identification Header

In addition to the bearer token, most API endpoints require a header to identify which user’s data you’re accessing. The header name varies by API:
  • x-user-id
The following APIs use the x-user-id header:
  • Investment Orders API - Submit and manage investment orders
  • Portfolios API - Access portfolio holdings and returns
  • Cash API - Retrieve user cash balances
  • Investment Products API (some endpoints) - Asset-specific data with user context
x-user-id: <user-identifier>
Example request to Investment Orders API:
curl -X POST "https://api.sandbox.wealthyhood.com/api/m2m/investments/orders" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-user-id: user-12345" \
  -H "Content-Type: application/json" \
  -d '{"isin": "US0378331005", "side": "buy", "amount": 1000}'
Example request to Cash API:
curl -X GET "https://api.sandbox.wealthyhood.com/cash" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-user-id: user-12345"
The user identifier must correspond to a valid user in the Wealthyhood platform. If you haven’t created a user yet, use the Users API to create one first.

​
Complete Authentication Flow

Here’s a complete example of the authentication flow from obtaining a token to making an authenticated API request:
1

Request an access token

Obtain a bearer token from the authentication server:
curl -X POST "<auth-endpoint-url>" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "audience": "<audience>",
    "client_id": "<client-id>",
    "client_secret": "<client-secret>"
  }'
Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "<scope>"
}
2

Make an authenticated API request

Use the access token and user identifier to access API endpoints:
curl -X GET "https://api.sandbox.wealthyhood.com/portfolio/holdings" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-user-id: user-12345"
If the request succeeds, you’re properly authenticated and can access all API endpoints.
Remember to use the correct user identification header (x-user-id) based on which API you’re calling.
3

Handle token expiration

When your token expires (after 3600 seconds in this example), request a new one using the same credentials:
Implement token refresh logic in your application to automatically request new tokens before expiration to maintain uninterrupted API access.