Authentication

Authentication Guide Overview

All BaaSReferralGateway API calls (except /healthcheck) require a valid Azure AD Bearer token obtained via the OAuth 2.0 client credentials flow. Green Dot provisions your Azure AD app registration and provides credentials per environment.

Architecture

Partner System
      |
      | HTTPS + Bearer Token (Azure AD)
      ↓
  Azure APIM
      | Validates JWT token
      | Enforces role claims
      ↓
  BaaSReferralGateway
      ↓
  Green Dot Platform

APIM validates the token and enforces role claims before requests reach the gateway. An invalid or expired token returns HTTP 401. A valid token missing a required role returns HTTP 403.

Step 1 - Obtain a Token

Post to Microsoft's token endpoint using your Green Dot-issued credentials:

POST https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={YOUR_CLIENT_ID}
&client_secret={YOUR_CLIENT_SECRET}
&scope=api://{AUDIENCE_ID}/.default

Parameters

Parameter	Value
`{TENANT_ID}`	`{TENANT_ID}` — same across all environments
`{YOUR_CLIENT_ID}`	Provided by Green Dot per environment
`{YOUR_CLIENT_SECRET}`	Provided by Green Dot per environment — treat as a secret, never log or expose
`{AUDIENCE_ID}`	Provided by Green Dot per environment — full scope value is `api://{AUDIENCE_ID}/.default`

For environment-specific Audience IDs, see Prerequisites & Onboarding.

Token Response

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1Qi..."
}

Step 2 - Use the Token

Pass the access_token value in the Authorization header on every API request:

Authorization: Bearer {access_token}

Token Caching & Refresh

Tokens expire after expires_in seconds (approximately 1 hour). Do not request a new token on every API call. The recommended approach:

Request a token and cache it in memory.
Track the expiry time (current_time + expires_in).
Proactively refresh the token when approximately 60–120 seconds remain before expiry.
On an unexpected 401 response, treat the cached token as stale, refresh immediately, and retry the request once.

Requesting a new token per API call adds latency and is unnecessary — tokens are valid for ~1 hour.

JWT Roles

Green Dot provisions two application roles on your service principal. Each role is required for a specific endpoint. Both roles must be present on your app registration before go-live.

Role	Required For	Effect if Missing
`ENROLLMENT`	`POST .../enrollment`	`HTTP 401` — request rejected before reaching the gateway
`ORDERCARD`	`PUT .../lifecycleEvent`	`HTTP 401` — request rejected before reaching the gateway

Common Request Headers

These headers apply to all API requests:

Header	Required	Value
`Authorization`	Yes (all except `/healthcheck`)	`Bearer {access_token}`
`X-GD-RequestId`	Yes (all)	A unique UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). Generate a fresh GUID per request — used for end-to-end tracing.
`Content-Type`	Yes (POST/PUT)	`application/json`
`X-Program-Code`	No	Used on the `/healthcheck` endpoint to route the probe to a specific program's downstream services in PROD.

About `X-GD-RequestId`

Generate a new UUID for every request - do not reuse request IDs.
Store the X-GD-RequestId you send alongside each transaction in your own logs. Green Dot Support uses this value for end-to-end request tracing when troubleshooting issues.
The idempotency behavior of the Enrollment API is keyed on this value - see the Enrollment API reference for details.

Client Timeout

Set your HTTP client timeout to at least 35 seconds. Enrollment calls synchronously run KYC and account creation — cutting off the connection before the server responds will not cancel the operation on Green Dot's side but will cause your client to miss the response.

Security Requirements

Store clientSecret and access_token values securely - never log them, include them in URLs, or expose them client-side.
Green Dot credentials are provided per environment - do not share credentials across DEV, QA, PIE, and PROD.
Rotate credentials if you suspect they have been compromised; contact your Green Dot integration contact immediately.

Next Steps

API Reference - Enrollment API, Order Card API, Health Check, and full error catalogs