Auth migration guide

Overview

The endpoint POST /auth is deprecated and retires on March 24, 2027.

To migrate, call POST /auth/tokens (Create Session Token) with your clientID and clientSecret, and send the returned Bearer token, plus the dw-client-app-key header, on every API call.

This is a credential change, not only a URL change. POST /auth/tokens does not accept your username, password, or appTypeID. See Before You Start.

Before You Start

You need three values for each environment. Sandbox and production credentials are separate.

Make the token request from your server only, never from a mobile app or browser. See the Authorization guide for how to protect these values.

Endpoint Replacement Matrix

Field Mapping

Request

The dw-client-app-key header is a new requirement, not a replacement for appTypeID. Send it on the token request and on every later API call.

Response

POST /auth/tokens also returns token_type (always Bearer).

Key normalization differences to handle in client code:

• expires_in is a string ("3600"), not a number. Parse it before you do any math.
• expiresAt was a timestamp. expires_in is a number of seconds, so compute the expiry from the time you made the request.
• access_token is a signed JWT. Don't log it.
• Every API call needs both Authorization: Bearer {access_token} and dw-client-app-key. A request without the app key fails even with a valid token.

Recommended Migration Pattern

1. Get your clientID, clientSecret, and dw-client-app-key for sandbox.

2. Replace the POST /auth request with POST /auth/tokens:

   Shell

   curl --location 'https://bo-api.drivewealth.io/back-office/auth/tokens' \
     --header 'dw-client-app-key: YOUR_APP_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "clientID": "YOUR_CLIENT_ID",
       "clientSecret": "YOUR_CLIENT_SECRET"
     }'

3. Send both headers on every API call:

   Shell

   curl --location 'https://bo-api.drivewealth.io/back-office/users/USERID' \
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'dw-client-app-key: YOUR_APP_KEY'

4. Cache the token and refresh it at about 55 minutes. Tokens last 60 minutes. Don't request a new token for each API call. DriveWealth expects roughly 5 to 10 token requests per hour per implementer.

5. Build a compatibility object for downstream consumers that still expect the old shape.

6. Repeat with production credentials against the production host.

Compatibility Object Example

{
    "authToken": "<from access_token>",
    "expiresAt": "<request time + expires_in seconds, as an ISO 8601 timestamp>",
    "userID": "<from userID>",
    "parentIBID": "<from partnerID>"
}

The old firstName and lastName are not in this response. Call GET /users/USERID with the returned userID.

Migration Checklist

• Replace all direct calls to POST /auth.
• Store the new clientID, clientSecret, and dw-client-app-key in a secrets manager, not in code or logs.
• Send Authorization: Bearer and dw-client-app-key on every API call.
• Parse expires_in as a string and refresh the token at about 55 minutes.
• Remove reads of authToken, expiresAt, firstName, and lastName from the token response. Read names from GET /users/USERID instead.
• Add integration tests for:
  • token request and response parsing,
  • both headers on downstream calls,
  • refresh before expiry,
  • behavior on 401.
• Remove the old username and password from code, configuration, and logs.

If a request returns 401, check these in order: the dw-client-app-key header, an expired token, the wrong environment, and rotated credentials. See the Authorization guide for the full list.