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

Parameter	Required (Y/N)	Format/Data Type	Pattern	Description
tenant_id	Yes	String	Max: 255	A value to specify the authentication domain. (To be provided by Green Dot.)
client_id	Yes	String	Max: 255	The ID associated with your account. (To be provided by Green Dot.)
client_secret	Yes	String	Max: 255	The secret associated with your account. (To be provided by Green Dot.)
scope	Yes	String	Max: 255	The scope for this authentication request. This is specific to the FSC API. (To be provided by Green Dot.)
grant_type	Yes	String	Max: 255	This 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

Parameter	Required (Y/N)	Format/Data Type	Pattern	Description
token_type	Yes	String	Max: 255	The type of token returned in the “access_token” field. This will always be “Bearer”.
expires_in	Yes	Numeric	Max: 10 digits	The number of seconds the token will be valid.
ext_expires_in	Yes	Numeric	Max: 10 digits	Used 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_token	Yes	String	Max: 255	The 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

Parameter	Required (Y/N)	Format/Data Type	Pattern	Description
error	Yes	String	Max: 255	An 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_description	Yes	String	Max: 255	A specific error message that might help you identify the root cause of an authentication error.
error_codes	No	Numberic	[1...] Max length of error_code: 10	A list of STS-specific error codes that might help with diagnostics.
timestamp	Yes	String	Max: 255	The time when the error occurred.
trace_id	Yes	String	Max: 255	A unique identifier for the request to help with diagnostics.
correlation_id	Yes	String	Max: 255	A 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 Code	Description	Client Action
invalid_request	Protocol error, such as a missing required parameter.	Fix and resubmit the request. This error is a development error typically caught during initial testing.
unauthorized_client	The 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_client	Client authentication failed.	The client credentials aren't valid. To fix, the application administrator updates the credentials.
invalid_scope	The requested scope is invalid, unknown, or malformed.	Fix and resubmit the request. This error is a development error typically caught during initial testing.
invalid_resource	The 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_error	The 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_unavailable	The 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

Parameter	Required (Y/N)	Format/ Data Type	Pattern	Description
access_token	Yes	String	Max: 255	The 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.