Authentication

You'll need to authenticate every request to access any of the Advisor endpoints in the advisor-api.wealth.com API. In this guide, we'll look at how authentication works. Wealth.com Advisor API uses header basic authentication value to authenticate each request.

Basic Authentication

Example request with auth

  curl --location 'https://advisor-api.wealth.com/v1/clients/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxxxxxxxxxxx' \
    --data '{
      "advisor_id": "cn4910ny98ec9vb3ghj",
      "team_id": "cn4910ny98ec9vb3ghj"
    }'

Please don't commit your Wealth.com Advisor API username or password to GitHub!

OAuth2 (User) Authentication

Use the OAuth2 Authorization Code flow for advisor user sign‑in. PKCE is recommended (and may be required) for public clients such as SPAs and native apps. After a successful authorization, your application will receive an access token.

Include the access token on requests using the Bearer scheme:

Authorization: Bearer <access_token>

Token verification expectations:

  • The token is a JWT access token signed using an asymmetric algorithm (RS256).
  • The token contains a kid header and can be verified against the authorization server's JWKS.
  • The token is not expired and includes standard claims such as iss (issuer) and sub (subject).
  • Use an access token only; ID tokens are not accepted for API calls.

About scopes: standard OIDC scopes (for example, openid, email, profile) and any configured custom scopes can be requested during authorization. Admission to endpoints is based on a valid access token; fine‑grained authorization is applied server‑side using the signed‑in advisor's profile and team membership.

Authorization Code flow overview

  1. Redirect the user to the authorization server with response_type=code, client_id, redirect_uri, requested scope, state, and for public clients a code_challenge (PKCE; use S256).
  2. After user authentication and consent, the authorization server redirects back to your redirect_uri with an authorization code (and the original state).
  3. Exchange the code at the token endpoint for tokens by sending grant_type=authorization_code, the code, your redirect_uri, and:
    • For confidential clients: client authentication.
    • For public clients using PKCE: the code_verifier.
  4. The token response includes an access_token and may include a refresh_token. Use only the access_token for API calls.

Refreshing access tokens:

  • Use the Refresh Token grant by sending grant_type=refresh_token and the refresh_token to obtain a new access_token when the current one expires.
  • Store refresh tokens securely (server‑side or platform‑secure storage).

Token lifetimes (subject to environment configuration):

  • Access tokens: short-lived, approximately 1 hour.
  • Refresh tokens: longer-lived, typically up to 30 days.

Endpoints accessible with OAuth2 (user) tokens

The following operations accept OAuth2 user tokens:

  • createClient
  • updateClient
  • getClient
  • listClients
  • getPrimaryDocumentRecommendation
  • getQuizQuestions

Other operations (such as deleting clients, asset management, top accounts, or document operations) are not available with OAuth2 user tokens. Client Credentials (m2m) tokens are not accepted for these user endpoints.