Introduction

BaaS API Authentication is using the OAuth 2.0 authentication protocol with machine-to-machine workflow.

This approach enables secure, automated communication between services without direct user intervention. By leveraging OAuth 2.0, BaaS (Banking as a Service) APIs can grant access tokens to trusted server applications, ensuring that only authorized machines can interact with backend resources. This method is widely adopted for its balance of security and scalability, making it ideal for modern cloud-based architecture where services often need to authenticate and authorize themselves independently.

📘

Please note that Partners are required to submit requests to have their production and development IP address ranges white-listed by Green Dot prior to accessing the BaaS API endpoints. Access will not be granted until this process is completed.

OAuth 2.0 is an industry-standard protocol for authorization, widely used to grant applications secure access to resources on behalf of a user or another system. Rather than sharing passwords, OAuth 2.0 allows users or services to authorize applications to access specific data or perform actions, using short-lived tokens as proof of permission.

At its core, OAuth 2.0 enables a secure way for applications to obtain limited access to protected resources—such as APIs or user data—without exposing sensitive credentials. It works through a system of “access tokens,” which are issued by an authorization server after successful authentication. These tokens can be tailored with specific permissions (called “scopes”) and typically expire after a short period, enhancing security.

OAuth 2.0 Machine-to-Machine Workflow

In a typical implementation, a client application first authenticates itself with an authorization server using defined credentials, such as a client ID and secret. Upon successful authentication, the server issues an access token—often a short-lived, cryptographically signed string—which the client then presents with each API call. The resource server, which hosts the protected endpoints, validates the token to confirm its authenticity and associated permissions before granting access to requested resources.

This model offers granular control over permissions and can easily accommodate scenarios where multiple services require different levels of access. Additionally, the OAuth 2.0 framework allows for the implementation of advanced security features, such as token refresh, scope limitation, and client certificate validation, further enhancing the resilience of the BaaS ecosystem against unauthorized access or misuse.

📘

Please note that the access token remains valid for 24 hours and must be requested again upon expiration.

Step 1: Requesting Access Token

To request an Access Token, the caller is required to use a valid ClientID and ClientSecret that are issued during partner onboarding.

The request for an access token involves making a POST request to the authorization BaaS token endpoint. The client application includes its ClientID and ClientSecret in the request header, encoded using HTTP Basic Authentication, ensuring credentials are transmitted securely. Alongside these credentials, the request specifies the intended grant type— “client_credentials” for machine-to-machine scenarios.

Upon successful verification of the provided credentials and parameters, the authorization server returns a JSON response containing the access token, its type (commonly “Bearer”), and metadata such as its expiration time and granted scopes. The client should securely store this token for subsequent API calls, always transmitting it in the HTTP Authorization header as “Bearer”.

It is essential to handle the token lifecycle diligently. Applications should monitor token validity and proactively request a new token upon or shortly before expiration to maintain uninterrupted access. It is recommended to cache the token for 23 hours to ensure uninterrupted access in high traffic scenarios.

The endpoint to request the access token:

{{BaasUrl}}/authentication

Required request headers:

Required request body values formatted as a JSON object:

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

The “Authorization” header value must be encoded in the following format:

“Basic ClientCredentials”

Where the ClientCredentials is an encoded Base64 string in the format of two concatenated values using a semicolon:

ClientId:ClientSecret

The ClientId and ClientSecret are provided during partner onboarding and must be kept secure on partner’s servers.

An example of a properly formatted “Authorization” header for the authentication:

Basic c3RyaW5nOnN0cmluZw==

The following C# example demonstrates how to prepare the “Authorization” header value and call the authentication endpoint:

// Prepare client credentials
string clientId = "your-client-id";
string clientSecret = "your-client-secret";
string credentials = $"{clientId}:{clientSecret}";
string base64Credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(credentials));
string authorizationHeader = $"Basic {base64Credentials}";

// Prepare the OAuth 2.0 request body
var authRequest = new 
{
    grant_type = "client_credentials",
    scope = "" 
};
string jsonBody = JsonSerializer.Serialize(authRequest);

// Create the HTTP request
using var httpClient = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://baas-api.com/authentication")
{
	// Add the body contents and set the content type to JSON
    Content = new StringContent(jsonBody, Encoding.UTF8, "application/json")
};
// Add encoded credentials
request.Headers.Add("Authorization", authorizationHeader);
// Add BaaS Request ID
request.Headers.Add("X-GD-RequestId", Guid.NewGuid().ToString());

// Send the request
HttpResponseMessage response = await httpClient.SendAsync(request);

// Read the response
string responseContent = await response.Content.ReadAsStringAsync();

If the authentication was successful, the following values will be returned in response as a JSON object:

{
    "access_token": string,
    "token_type": string,
    "expires_in": number,
    "scope": string
}

An example of successful authentication:

{
    "access_token": "Fq0pdt9WXbrKhFWqGrx1jQ==",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scope": "general demo"
}

In this example, the "access_token" is a unique string representing the access token granted to the client. The "token_type" indicates the protocol used—in this case, "Bearer"—which means the token must be included in the HTTP Authorization header to authorize subsequent requests. The "expires_in" field specifies the number of seconds the token remains valid, after which a new token must be obtained. The "scope" outlines what permissions have been authorized for this token, allowing for fine-grained access control within the system.

If the authentication was not successful, BaaS API will return the following error codes in response:

Step 2: Accessing Protected BaaS API endpoints

Once you have obtained a valid access token, you can interact with the protected BaaS (Backend as a Service) API endpoints by including the token in the Authorization header of your HTTP requests. For example, to access a user profile or fetch application data, ensure your request header follows this format:

Authorization: Bearer access_token

The server will verify the token, check its validity and scope, and grant access to the requested resources if the token is authorized. If the token has expired or lacks the required scope, the server will deny the request and will return an error indicating that authentication is needed or insufficient privileges exist. Always ensure that your token is kept secure and never exposed in client-side code or logs, as it represents the key to accessing protected system resources.

The following C# example demonstrates how to access a protected API endpoint using OAuth 2.0 access token:

// Your OAuth 2.0 access token
string accessToken = "your-access-token";
// Create the HttpClient
using var httpClient = new HttpClient();
// Add the Authorization header for Bearer token
httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
// Add BaaS Request ID
httpClient.DefaultRequestHeaders.Add("X-GD-RequestId", Guid.NewGuid().ToString());
// Make the API request (GET in this example)
var response = await httpClient.GetAsync("https://baas-api.com/protected-endpoint");
// Read the response content as a string
string responseContent = await response.Content.ReadAsStringAsync();

If the access token expires prior to the API call, a "401 Unauthorized" error will be returned. In such cases, it is necessary to repeat the authentication process as outlined in Step 1.

To prevent repeated failures due to token expiration, consider implementing automatic token refresh logic. Before making each API request, you can validate the token's expiry and obtain a new token if necessary.