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 hello@wealthyhood.com 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:
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/portfolios" \
  -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.