Guides

Testing

Getting Started: Testing Green Dot BaaS APIs

This guide explains how to begin testing Green Dot Banking‑as‑a‑Service (BaaS) APIs after credentials have been provisioned. It is intended for partners who have completed onboarding and are ready to make authenticated API calls.

BaaS APIs use an OAuth 2.0 machine‑to‑machine (client credentials) authentication model. Some APIs also require field‑level encryption for sensitive data. Understanding both is essential for successful end‑to‑end testing.

At a high level, testing BaaS APIs involves:

  1. Authenticating to obtain a bearer (access) token
  2. Calling BaaS APIs using that token
  3. Encrypting request and response payloads where required
📘

Before testing any BaaS APIs, your machine’s IP address must be allow‑listed by Green Dot. API requests will be blocked until allow‑listing is complete, even if credentials have been issued.

Prerequisites

Before testing BaaS APIs, ensure all of the following steps are complete:

  • Partner onboarding has been completed
  • You have received a Client ID and Client Secret from Green Dot
  • Your development and/or production IP address ranges have been allow‑listed by Green Dot
  • You know which environment you are testing (Sandbox or Production)
  • You have an HTTP client available (for example: Postman, curl, Insomnia, or a custom client)

Important

Client credentials must be stored securely on partner‑managed servers and must never be exposed in client‑side code, logs, or public repositories.

Overview: How BaaS API Testing Works

All BaaS API interactions follow the same core pattern:

  1. Use OAuth 2.0 client credentials to request an access token
  2. Include the access token as a Bearer token in API requests
  3. Encrypt sensitive request or response fields when required

Authentication is mandatory for all APIs. Encryption is required only for APIs and fields explicitly marked as encrypted in the API reference.

Step 1: Authenticate and Retrieve a Bearer Token

All BaaS API calls require a valid bearer token. Bearer tokens are obtained from the Authentication API.

  • The token is temporary
  • Tokens can be reused until expiration
  • You will request it again when it expires
  • You do not embed credentials in every API call
📘

Access tokens are valid for 24 hours.

For full authentication details, see:

BaaS API Authentication

Authentication Model

BaaS API Authentication uses the OAuth 2.0 client credentials grant type, which supports secure machine‑to‑machine communication without user interaction.

  • Tokens are issued to server applications, not users
  • Tokens are short‑lived and must be refreshed upon expiration
  • Tokens are scoped to the permissions granted during onboarding

Authentication Request Overview

  • Endpoint: /authentication
  • Method: POST
  • Grant Type: client_credentials
  • Authentication Type: HTTP Basic Authentication

Required Request Headers

Authorization: Basic {Base64EncodedClientCredentials}
Content-Type: application/json
X-GD-RequestId: {new-guid-per-request}

Constructing the Authorization Header

The Authorization header must use Basic Authentication, where the client credentials are Base64‑encoded.

  1. Concatenate your Client ID and Client Secret using a colon:
ClientId:ClientSecret
  1. Base64‑encode the entire string.

Final header format:

Authorization: Basic {Base64EncodedClientId:ClientSecret}

Example

Authorization: Basic c3RyaW5nOnN0cmluZw==

Notes

  • Only ClientId:ClientSecret is Base64‑encoded
  • Do not encode the word Basic

Required Request Body

{
  "grant_type": "client_credentials",
  "scope": ""
}

Authentication Response

A successful authentication request returns a JSON response containing an access token:

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "string"
}

Reminders:

  • Access tokens are valid for 24 hours
  • Tokens can be reused until expiration
  • Request a new token once the current token expires

Step 2: Call BaaS APIs Using the Bearer Token

Once a bearer token has been obtained, include it in the Authorization header for all subsequent BaaS API requests.

Required Header

Authorization: Bearer {access_token}

Example

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

This header is required for all protected BaaS APIs, including account, card, transaction, and disbursement endpoints.

Authorization Errors

If authentication fails or the token is invalid, the API may return:

  • 401 Unauthorized - missing, expired, or invalid token
  • 403 Forbidden - insufficient permissions or scope

If this occurs:

  • Request a new access token
  • Confirm you are using the correct environment
  • Verify your IP address is allow‑listed

Step 3: Encrypt Sensitive Data (When Required)

Some BaaS APIs require field‑level encryption for sensitive data, in addition to standard TLS transport encryption.

Examples include:

  • Personally identifiable information (PII)
  • Dates of birth
  • Social Security Numbers
  • Certain payment instrument details

Encrypted fields are clearly identified in the API reference and typically use an encrypted* naming convention (for example, encryptedUserData).

Important Notes About Encryption

  • Encryption is not required for all APIs
  • If encryption is required, plain JSON requests will fail
  • Both request payloads and response payloads may require encryption/decryption
  • Encryption testing typically requires implementing cryptographic logic in code rather than using a basic HTTP client

Before testing encrypted APIs:

  • Public encryption keys must be exchanged between Green Dot and the partner
  • Refer to the Encryption in BaaS API documentation for full implementation details

Typical End‑to‑End Testing Flow

  1. Authenticate using client credentials
  2. Receive an OAuth 2.0 bearer token
  3. Prepare API request payload
  4. Encrypt sensitive fields if required
  5. Call the BaaS API using the Bearer token
  6. Decrypt encrypted response fields if present

Environment Considerations

  • Sandbox credentials generate tokens for Sandbox APIs
  • Production credentials generate tokens for Production APIs
  • Tokens cannot be reused across environments

Common Issues to Avoid

  • Forgetting to Base64‑encode ClientId:ClientSecret
  • Omitting Basic or Bearer from the Authorization header
  • Using expired access tokens
  • Attempting to test encrypted APIs without encryption implemented
  • Using non‑allow‑listed IP addresses
  • Exposing secrets in client‑side applications

Next Steps

Once authentication is working:

  • Identify which APIs and fields require encryption
  • Review the Encryption in BaaS API documentation
  • Implement encryption and decryption logic as needed
  • Validate request and response payloads
  • Progress from Sandbox testing to Production readiness

Summary

  • All BaaS APIs require OAuth 2.0 authentication
  • Authentication uses the client‑credentials grant type
  • Access tokens are obtained using Base64‑encoded Basic Authorization
  • Bearer tokens must be sent with every API request
  • Some APIs require additional field‑level encryption
  • Successful testing may require both authentication and encryption to be fully implemented

Updated about 9 hours ago