Authentication

Service Authentication

To access the FSC Service, the client’s IP address must be whitelisted. In addition, the caller must be authenticated using OAuth 2.0 authentication and use the generated access token in the authorization header in all requests that require it. The authentication credentials will be provided by Green Dot.

Token Generation (Authentication)

The Microsoft OAuth 2.0 service is used for authentication. A standard JWT bearer token will be generated and will be used when calling the FSC APIs. The necessary values for the authentication will be provided by Green Dot during your onboarding.

Request

Request Format

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

client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials&scope={scope}

Request Parameters

ParameterRequired (Y/N)Format/Data TypePatternDescription
tenant_idYesStringMax: 255A value to specify the authentication domain. (To be provided by Green Dot.)
client_idYesStringMax: 255The ID associated with your account. (To be provided by Green Dot.)
client_secretYesStringMax: 255The secret associated with your account. (To be provided by Green Dot.)
scopeYesStringMax: 255The scope for this authentication request. This is specific to the FSC API. (To be provided by Green Dot.)
grant_typeYesStringMax: 255This must be set to “client_credentials”.

Example Request

POST https://login.microsoftonline.com/7f6bcd3a-7ec3-4e56-b0aa-c1b641c97749/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=9cf15f44-acba-4d70-bbe0-8596ba407d12&client_secret=5C5nfdPT3~VpAFmtZLB54Ajr6m9VRj5mzmvhQB7z&grant_type=client_credentials&scope=api%3A%2F%2Fe00fc43f-92c3-4b3a-988d-142bda692127%2F.default

Response

Response Format

{
    "token_type": "{type}",
    "expires_in": {expires_in},
    "ext_expires_in": {ext_expires_in},
    "access_token": "{token}"
}

Response Parameters

ParameterRequired (Y/N)Format/Data TypePatternDescription
token_typeYesStringMax: 255The type of token returned in the “access_token” field. This will always be “Bearer”.
expires_inYesNumericMax: 10 digitsThe number of seconds the token will be valid.
ext_expires_inYesNumericMax: 10 digitsUsed to indicate an extended lifetime for the access token and to support resiliency when the token issuance service is not responding. This can be safely ignored for this scenario.
access_tokenYesStringMax: 255The access_token generated by the authentication request. This will be passed into future API calls.

Example Response

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ii1LSTNROW5OUjdiUm9meG1lWm9xvnQTpQjqqfHL_TPQc48Smwm7pZ75QRkdIq2PZdtnftMO47pyp2GwBBXE2YEgprw4LGahUpSCkN8uekXhibN9Z43ffis3yaubYcWJIWkdldyIsImtpZCI6Ii1LSTNROW5OUjdiUm9meG1lWm9YcWJIWkdldyJ9.eyJhdWQiOiJhcGk6Ly9lMDBmYzQzZi05MmMzLTRiM2EtOTg4ZC0xNDJiZGE2OTIxMjciE4ZiIsImFwcGlkYWNyIjoiMSIsImlkcCI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzdmNmJjZDNhLTdlYzMtNGU1Ni1iMGFhLWMxYjY0MWM5Nzc0OS8iLCJvaWQiOiJjNjAxYzQ4MC1hOTI4LTQ2YzAtOGQzZi0xMzA4MTcwY2Q0ODIiLCJyaCI6IjAuQLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZjZiY2QzYS03ZWMzLTRlNTYtYjBhYS1jMWI2NDFjOTc3NDkvIiwiaWF0IjoxNjkwOTEyNDYyLCJuYmYiOjE2OTA5MTI0NjIsImV4cCI6MTY5MDkxNjM2MiwiYWlvIjoiRTJGZ1lKajI3ZkdWcjZHMkJ3N3VMZXJZdlVXc0JRQT0iLCJhcHBpZCI6IjY1ZDAxZWJiLTk4NzAtNGQ2MS05Yjc0LWFiNDhiYTdjZjVJNQU9zMXJmOE4tVms2d3FzRzJRY2wzU1RfRUQtRERranBMbUkwVUs5cHBJU2ZhQUFBLiIsInN1YiI6ImM2MDFjNDgwLWE5MjgtNDZjMC04ZDNmLTEzMDgxNzBjZDQ4MiIsInRpZCI6IjdmNmJjZDNhLTdlYzMtNGU1Ni1iMGFhLWMxYjY0MWM5Nzc0OSIsInV0aSI6IjBfMUQxbVI5YWt5QlA0N3NjeTFCQUEiLCJ2ZXIiOiIxLjAifQ.q_x35zin3IXfx97gzAkwySacJyGA9Ju5kmpm96obyJo5FtCW0Ll5ELF8mmqVEfCYf6TVjkMYNJrMUj2iL7181oZSalRnNj5chOsr86UiM4vH4h7LBy3uYztEsLg2hriBfkMtBIS6VAoQJHKetSa_EgizcKDosS7zqHGJ9ZBn21ZYb0uyC99AuRjFMprnVrUEvXzU3p5Xnl8ehiVCgwldFApeeCCBWHqjlfDIVW7A946BBUEfOLHTQ"
}

Error

Error Response Format

{
  "error": "{error}",
  "error_description": "{description}",
  "error_codes": [
    {error_code},
    …
  ],
  "timestamp": "{timestamp}",
  "trace_id": "{trace_id}",
  "correlation_id": "{correlation_id}"
}

Error Response Parameters

ParameterRequired (Y/N)Format/Data TypePatternDescription
errorYesStringMax: 255An error code string that you can use to classify types of errors that occur, and to react to errors. (See “Errors and Descriptions” below.)
error_descriptionYesStringMax: 255A specific error message that might help you identify the root cause of an authentication error.
error_codesNoNumberic[1...]
Max length of error_code: 10
A list of STS-specific error codes that might help with diagnostics.
timestampYesStringMax: 255The time when the error occurred.
trace_idYesStringMax: 255A unique identifier for the request to help with diagnostics.
correlation_idYesStringMax: 255A unique identifier for the request to help with diagnostics across components.

Example Error Response

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "YYYY-MM-DD HH:MM:SSZ",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}

Error Descriptions

Error CodeDescriptionClient Action
invalid_requestProtocol error, such as a missing required parameter.Fix and resubmit the request. This error is a development error typically caught during initial testing.
unauthorized_clientThe client application isn't permitted to request an authorization code.This error usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD.
invalid_clientClient authentication failed.The client credentials aren't valid. To fix, the application administrator updates the credentials.
invalid_scopeThe requested scope is invalid, unknown, or malformed.Fix and resubmit the request. This error is a development error typically caught during initial testing.
invalid_resourceThe target resource specified by the scope is invalid because it doesn't exist, Azure AD can't find it, or it's not correctly configured.This error indicates the resource specified by the scope, if it exists, hasn't been configured in the tenant. Validate that the scope is correct and try again.
server_errorThe server encountered an unexpected error.Retry the request. These errors can result from temporary conditions. The client application might explain to the user that its response is delayed to a temporary error.
temporarily_unavailableThe server is temporarily too busy to handle the request.Retry the request. The client application might explain to the user that its response is delayed because of a temporary condition.

Additional Resources

Token Usage (Authorization)

Every API calls that requires authorization needs to include the following header.

Request

Request Headers

Authorization: Bearer {access_token}

Request Parameters

ParameterRequired (Y/N)Format/ Data TypePatternDescription
access_tokenYesStringMax: 255The access token value obtained from the authenticate API call.

Request Example

POST {baseUrl}/registration/validate
Authorization: bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ii1LSTNROW5OUjdiUm9meG1lWm9xvnQTpQjqqfHL_TPQc48Smwm7pZ75QRkdIq2PZdtnftMO47pyp2GwBBXE2YEgprw4LGahUpSCkN8uekXhibN9Z43ffis3yaubYcWJIWkdldyIsImtpZCI6Ii1LSTNROW5OUjdiUm9meG1lWm9YcWJIWkdldyJ9.eyJhdWQiOiJhcGk6Ly9lMDBmYzQzZi05MmMzLTRiM2EtOTg4ZC0xNDJiZGE2OTIxMjciE4ZiIsImFwcGlkYWNyIjoiMSIsImlkcCI6Imh0dHBzOi8vc3RzLndpbmRvd3MubmV0LzdmNmJjZDNhLTdlYzMtNGU1Ni1iMGFhLWMxYjY0MWM5Nzc0OS8iLCJvaWQiOiJjNjAxYzQ4MC1hOTI4LTQ2YzAtOGQzZi0xMzA4MTcwY2Q0ODIiLCJyaCI6IjAuQLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZjZiY2QzYS03ZWMzLTRlNTYtYjBhYS1jMWI2NDFjOTc3NDkvIiwiaWF0IjoxNjkwOTEyNDYyLCJuYmYiOjE2OTA5MTI0NjIsImV4cCI6MTY5MDkxNjM2MiwiYWlvIjoiRTJGZ1lKajI3ZkdWcjZHMkJ3N3VMZXJZdlVXc0JRQT0iLCJhcHBpZCI6IjY1ZDAxZWJiLTk4NzAtNGQ2MS05Yjc0LWFiNDhiYTdjZjVJNQU9zMXJmOE4tVms2d3FzRzJRY2wzU1RfRUQtRERranBMbUkwVUs5cHBJU2ZhQUFBLiIsInN1YiI6ImM2MDFjNDgwLWE5MjgtNDZjMC04ZDNmLTEzMDgxNzBjZDQ4MiIsInRpZCI6IjdmNmJjZDNhLTdlYzMtNGU1Ni1iMGFhLWMxYjY0MWM5Nzc0OSIsInV0aSI6IjBfMUQxbVI5YWt5QlA0N3NjeTFCQUEiLCJ2ZXIiOiIxLjAifQ.q_x35zin3IXfx97gzAkwySacJyGA9Ju5kmpm96obyJo5FtCW0Ll5ELF8mmqVEfCYf6TVjkMYNJrMUj2iL7181oZSalRnNj5chOsr86UiM4vH4h7LBy3uYztEsLg2hriBfkMtBIS6VAoQJHKetSa_EgizcKDosS7zqHGJ9ZBn21ZYb0uyC99AuRjFMprnVrUEvXzU3p5Xnl8ehiVCgwldFApeeCCBWHqjlfDIVW7A946BBUEfOLHTQ
Content-Type: application/json
{ ... }

Authorization Error

If a token is not valid for any reason, it will cause an “HTTP 401 Unauthorized” error to be returned with no response body. An expired token, a malformed token, or using a token generated for a different app will all return a 401. There will be no indication as to reason. At this point you will need to go through the authentication process again to obtain a valid access token.