Authentication - Future Demand Developer Kit

The Future Demand Client API uses AWS Cognito as its identity provider. Every authenticated request carries a Bearer access token plus a header that tells the backend which partner (tenant) you’re acting under.

The OpenAPI spec lists a security scheme called apikey, but its description says Copy your Cognito JWT Token below: 'Bearer <JWT>'. There is no separate static API key — you obtain a JWT the same way the reference webapp does, via POST /auth. Treat any “API key” mention in the spec as “Bearer JWT”.

The two headers you always send

Authorization: Bearer <access_token>
X-Preferred-Partner-Id: <partner_id>

Header	Required?	What it is
`Authorization`	Always	Cognito `AccessToken` returned from `/auth`. Refresh ~5 min before `ExpiresIn`.
`X-Preferred-Partner-Id`	Always when the user belongs to >1 partner; safest to always send	The partner the request applies to. Must be one of the user’s `cognito:groups` matching `/(partner-id-.+	fd\d+)/`. The backend scopes all reads/writes by this.

The reference webapp attaches both via an axios transformRequest (see webapp/src/api/_init.js). Mirror this in your client.

curl -s -X POST "https://client-api.prd.future-demand.com/api/v3/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@partner.com",
    "password": "hunter2"
  }'

The response is one of three shapes — branch on the presence of AccessToken and the value of Challenge:

Success (no MFA)
MFA challenge
Force new password

{
  "AccessToken":   "eyJraWQ...",
  "IdToken":       "eyJraWQ...",
  "RefreshToken":  "eyJjdHkiOiJKV1Q...",
  "ExpiresIn":     3600,
  "TokenType":     "Bearer",
  "DeviceKey":      null,
  "DeviceGroupKey": null,
  "mfa_settings":  { "required": false, ... }
}

Store the three tokens and the expiry. Compute tokenExpirationDate = now() + ExpiresIn (seconds).

{
  "Challenge":        "SOFTWARE_TOKEN_MFA",
  "ChallengeSession": "abc123...",
  "mfa_settings":     { "preferred_mfa": "SOFTWARE_TOKEN_MFA", ... }
}

Prompt the user for their OTP, then call /auth/challenge/mfa-token (see §3).

{
  "Challenge":         "NEW_PASSWORD_REQUIRED",
  "ChallengeSession":  "xyz789..."
}

This happens on first login for newly-provisioned users. Respond at PUT /auth/challenge/new-password with {username, session, new_password}.

Decoding the IdToken

The IdToken is a standard JWT. Decode it client-side (e.g. with jwt-decode) to read user claims:

import { jwtDecode } from "jwt-decode";

const claims = jwtDecode<{
  sub: string;
  email: string;
  name?: string;
  "cognito:groups": string[];
  "custom:multi_partner_view"?: "name" | "id";
}>(response.IdToken);

// Extract partner memberships
const partnerIds = (claims["cognito:groups"] ?? [])
  .filter(g => /^(partner-id-.+|fd\d+)$/.test(g));

Special group markers — reject login if any are present:

account-disabled — the account is suspended.
external-user — not allowed to log into a first-party app.

Admin-only markers (you usually don’t expose admin features to partners): fd-admin, back-office-admin, webapp-access-group-<N>.

2. Make authenticated requests

curl -s "https://client-api.prd.future-demand.com/api/v3/partners/" \
  -H "Authorization: Bearer $FD_ACCESS_TOKEN" \
  -H "X-Preferred-Partner-Id: $FD_PARTNER_ID"

The reference webapp dispatches a global LOGOUT on any 401 response — no auto-retry. If your client behaves the same, make sure your token refresh runs before the request goes out (proactive), not as a 401 fallback.

3. Multi-factor authentication

MFA is mandatory for end-user logins after 2025-05-12.

Respond to a challenge

PUT /auth/challenge/mfa-token
{
  "username":         "user@partner.com",
  "session":          "<ChallengeSession from /auth>",
  "mfa_token":        "123456",
  "mfa_method":       "SOFTWARE_TOKEN_MFA" | "EMAIL_OTP",
  "remember_device":  true
}

A successful response carries the same tokens as a non-MFA login, plus DeviceKey and DeviceGroupKey if remember_device: true was set. Cache them per-user — passing them on the next /auth call lets the user skip the MFA prompt on a trusted device.

Endpoint	Purpose
`GET /auth/mfa/settings`	Current MFA state for the user
`PUT /auth/mfa/settings`	Enable / disable / set preferred MFA method
`GET /auth/mfa/configure/totp`	Get `qr_uri` + `qr_secret` for authenticator-app enrolment
`PUT /auth/mfa/configure/totp`	Verify the TOTP setup with a `mfa_token`

4. Refresh tokens

Access tokens expire after one hour. Refresh proactively when less than 5 minutes remain, not on the failed 401:

curl -s -X POST "https://client-api.prd.future-demand.com/api/v3/auth/refresh_token" \
  -H "Content-Type: application/json" \
  -d '{
    "token":            "'"$FD_REFRESH_TOKEN"'",
    "device_key":       null,
    "device_group_key": null
  }'

Response:

{ "AccessToken": "eyJ...", "IdToken": "eyJ...", "TokenType": "Bearer" }

The refresh token does not rotate. Keep using the original RefreshToken from the initial /auth call until the user signs out or it eventually expires (Cognito default: 30 days).

See Cookbook: Token refresh for a complete fetch/axios interceptor.

5. Forgot / reset password

Initiate

POST /auth/initiate_forgot_password
{ "email": "user@partner.com" }

User receives a confirmation code by email.

Confirm

POST /auth/confirm_forgot_password
{ "email": "...", "conf_code": "123456", "new_password": "newSecret!" }

6. Create users under a partner

If you’re letting partner-admins onboard users:

POST /auth/partners/{partner_id}/users
{
  "email":       "new@partner.com",
  "password":    "Temp123!",
  "given_name":  "Ada",
  "family_name": "Lovelace",
  "partner_id":  "partner-id-acme"
}

The user receives a confirmation code. Complete with POST /auth/partners/users/confirm ({email, conf_code}).

7. Logout

There is no server-side token revocation. Tokens remain valid until their natural expiry. To log a user out:

Drop the access token, ID token, and refresh token from your client store.
Clear any DeviceKey / DeviceGroupKey you cached for “remember device”.

If your integration is server-to-server, treat logout as “drop the cached session”.

8. Permissions and features

After login, fetch two things to drive your UI:

# Per-partner permission strings (re-fetch on partner switch)
curl -s "https://client-api.prd.future-demand.com/api/v3/permissions" \
  -H "Authorization: Bearer $FD_ACCESS_TOKEN" \
  -H "X-Preferred-Partner-Id: $FD_PARTNER_ID"

# Feature flags for this partner
curl -s "https://client-api.prd.future-demand.com/api/v3/features" \
  -H "Authorization: Bearer $FD_ACCESS_TOKEN" \
  -H "X-Preferred-Partner-Id: $FD_PARTNER_ID"

Use permissions for “can this user open the campaign editor?” decisions and features for “is the Wave wizard enabled for this partner?” toggles.

9. Error model

Status	Meaning	What to do
`401`	Missing/expired token, or admin marker tripped (`account-disabled`).	Re-authenticate. The reference webapp force-logs-out on any 401.
`403`	Authenticated but not authorised for this partner/resource.	Check `X-Preferred-Partner-Id` matches a group the token actually has.
`400`	Validation.	Inspect `validation_errors[]` in the response body.
`429`	Rate limit.	Back off — see Rate limits.

Response shape on errors:

{
  "message":      "error.auth.invalid_credentials",
  "error_code":   "INVALID_CREDENTIALS",
  "error_subcode": null,
  "validation_errors": [{ "code": "..." }]
}

The message is an i18n key (always starts with error.); map it to your own copy. Log error_code and the x-request-id response header in any support ticket.

Security checklist

Never ship long-lived tokens to a browser

Access tokens are short-lived (~1h) and acceptable in a browser. The refresh token is long-lived — keep it on your backend if your UI is web-based, or use a secure storage API on native.

Always send X-Preferred-Partner-Id

Even if your user belongs to only one partner. Omitting it on multi-partner accounts will scope your call to an arbitrary partner.

Refresh proactively

Track ExpiresIn and refresh when less than 5 minutes remain. Don’t refresh on 401 — your user request has already failed by then.

Don't put tokens in URLs

Always the Authorization header. URLs end up in access logs and browser history.

Pin staging vs production

Use distinct credentials per environment in your CI/CD secrets. Production credentials must never appear in staging logs.

​The two headers you always send

​1. Sign in

​Decoding the IdToken

​2. Make authenticated requests

​3. Multi-factor authentication

​Respond to a challenge

​Configure MFA (post-login)

​4. Refresh tokens

​5. Forgot / reset password

​6. Create users under a partner

​7. Logout

​8. Permissions and features

​9. Error model

​Security checklist

The two headers you always send

1. Sign in

Decoding the IdToken

2. Make authenticated requests

3. Multi-factor authentication

Respond to a challenge

Configure MFA (post-login)

4. Refresh tokens

5. Forgot / reset password

6. Create users under a partner

7. Logout

8. Permissions and features

9. Error model

Security checklist