Authorize

Select the following:
Home

>

API Products

>

India - Authorize API Documentation

Authorize

Summary

Authorize is our implementation of the OAuth 2.0 framework. It enables secure authorization using standard methods that can easily be integrated in your app. If you're familiar with OAuth 2.0, everything should look familiar. If not, you may want to check out the OAuth 2.0 resources here.

Want to try this API out on our Playground?

Go play now
Endpoints on this page
post /clientCredentials/oauth2/token/in/gcb Client Credentials Grant: Retrieve Access Token
get /authCode/oauth2/authorize Authorization Code Grant: Retrieve Authorization Code
post /authCode/oauth2/refresh Authorization Code Grant: Refresh Access Token
post /authCode/oauth2/revoke Authorization Code Grant: Revoke Access Token
post /authCode/oauth2/token/in/gcb Authorization Code Grant: Retrieve Access Token

Client Credentials Grant: Retrieve Access Token

post /clientCredentials/oauth2/token/in/gcb
Description

This API is used to retrieve the access token for your application credentials. You can use this for APIs which do not require customer credential verification and consent (e.g. Onboarding).

Swagger
Header Parameters
Authorization
string required
HTTP Basic authentication by passing base64 encoded value of the client id and client secret separated by colon (:).Example: Base64(client_id:client_secret) will be passed as Basic KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==
Content-Type
string required
Value should always be application/x-www-form-urlencoded
FormData Parameters
grant_type
string required
The grant type. Valid value is client_credentials.
scope
string required
The set of scopes requested to make API calls. You can pass multiple values delimted by space
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

The request has succeeded
Definitions
  • access_token
    • The access token value received after exchanging the authorization token. This field should be passed as Authorization header in API request calls
    • type : string
  • refresh_token
    • You can use this token to refresh an expired access_token.
    • type : string
  • scope
    • Set of scopes allowed by customer and separated by space
    • type : string
  • token_type
    • Type of the access token issued. This is bearer token for authorization_code grant type
    • type : string
  • expires_in
    • Validity of access token in seconds
    • type : number
Example Response for post /clientCredentials/oauth2/token/in/gcb
400

error
invalid_request
invalid_grant
unsupported_grant_type
unauthorized_client
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /clientCredentials/oauth2/token/in/gcb 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
401

error
invalid_client
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /clientCredentials/oauth2/token/in/gcb 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
500

server_error
This operation returns no content.

Authorization Code Grant: Retrieve Authorization Code

get /authCode/oauth2/authorize
Description

This API is used to validate the customer credentials in Citi login Page and redirect back the authorisation code post successful validation.

Swagger
Query Parameters
response_type
string required
Value MUST be set to "code"
client_id
string required
Client ID generated during application registration.
scope
string required
The set of scopes required to make the API calls. Scope is case insensitive and multiple values can be passed using space delimiter.
countryCode
string required
Country code in 2 character ISO 3166 format (upper case)
businessCode
string required
The 3 character business code. Use GCB for consumer banking (upper case)
locale
string required
Locale identify a specific language and geographic region, it shoule follow [language[_territory]. eg - en_US, en_SG
state
string required
Opaque value to maintain the state between request and call back. This will be used to prevent cross-site request forgery.
redirect_uri
string required
Absolute uri for user-agent redirection.You should provide the uri used during client registration process.
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

Client Authentication
This operation returns no content.
302

The authorization response contains the authorization code needed to obtain an access token. Here are the parameters included in the response.
success response
field namefield typemandatorydescription
redirect_urilocationyesThis is the absolute uri provided in the request
codequeryyesThe authorization code
statequeryyesThe same value as sent by the client in the state parameter, if any

If an error occurs during authorization, two situations can occur. The first is, that the client is not authenticated or recognized. For instance, a wrong redirect URI was sent in the request. In that case the authorization server must not redirect the resource owner to the redirect URI. Instead it should inform the resource owner of the error. The second situation is that client is authenticated correctly, but that something else failed. In that case the following error response is sent to the client, included in the redirect_uri
failure response
field namefield typemandatorydescription
redirect_urilocationyesThis is the absolute uri provided in the request
statequeryyesThe same value as sent by the client in the state parameter, if any
errorqueryyes
error_descriptionqueryno
error_uriqueryno

Here is the list of errors:
error
invalid_request
unauthorized_client
unsupported_response_type
invalid_scope
access_denied
This operation returns no content.
500

server_error
This operation returns no content.
503

temporarily_unavailable
This operation returns no content.

Authorization Code Grant: Refresh Access Token

post /authCode/oauth2/refresh
Description

This API is used to exchange for a new set of valid access and refresh tokens in case access token has expired and still have a valid refresh token.

Swagger
Header Parameters
Authorization
string required
HTTP Basic authentication by passing base64 encoded value of the client id and client secret separated by colon (:).Example: Base64(client_id:client_secret) will be passed as Basic KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==
Content-Type
string required
Content type. Value is application/x-www-form-urlencoded
FormData Parameters
grant_type
string required
The grant type. Valid value is refresh_token.
refresh_token
string required
The refresh token issued to the client
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

The request has succeeded
Definitions
  • access_token
    • This field should be passed as Authorization header in API request calls
    • type : string
  • refresh_token
    • The refresh token value
    • type : string
  • scope
    • The list of scopes separated by space
    • type : string
  • token_type
    • The token type
    • type : string
  • expires_in
    • The access token expiry time (in seconds)
    • type : number
Example Response for post /authCode/oauth2/refresh
400

error
invalid_request
invalid_grant
unsupported_grant_type
unauthorized_client
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /authCode/oauth2/refresh 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
401

error
invalid_client
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /authCode/oauth2/refresh 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
500

server_error
This operation returns no content.

Authorization Code Grant: Revoke Access Token

post /authCode/oauth2/revoke
Description

This API is used to revoke the access token. Along with the access token, the corresponding refresh token is also revoked and vice-versa.

Swagger
Header Parameters
Authorization
string required
HTTP Basic authentication by passing base64 encoded value of the client id and client secret separated by colon (:).Example: Base64(client_id:client_secret) will be passed as Basic KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==
Content-Type
string required
Content type. Value is application/x-www-form-urlencoded
FormData Parameters
token
string required
The token to be revoked
token_type_hint
string required
A hint about the type of the token submitted for revocation. Clients MAY pass this parameter in order to help the authorization server to optimize the token lookup. Valid values are access_token, refresh_token
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

The request has succeeded
Definitions
  • status
    • The status of the token revocation request.
    • type : string
Example Response for post /authCode/oauth2/revoke
400

error
invalid_request
invalid_grant
unauthorized_client
unsupported_grant_type
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /authCode/oauth2/revoke 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
401

error
invalid_client
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /authCode/oauth2/revoke 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
500

server_error
This operation returns no content.

Authorization Code Grant: Retrieve Access Token

post /authCode/oauth2/token/in/gcb
Description

This API is used to validate the authorisation code and return back the access token.

Swagger
Header Parameters
Authorization
string required
HTTP Basic authentication by passing base64 encoded value of the client id and client secret separated by colon (:).Example: Base64(client_id:client_secret) will be passed as Basic KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==
Content-Type
string required
Value should always be application/x-www-form-urlencoded
FormData Parameters
grant_type
string required
Authentication grant type. Valid value is authorization_code
code
string required
The code from the response of GET /authCode/oauth2/authorize
redirect_uri
string required
Absolute uri for user-agent redirection. You should provide the uri passed in GET /authCode/oauth2/authorize request
  • cURL
  • Ruby
  • Python
  • PHP
  • Java
  • Node
  • Go
  • Swift

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Example Request

Responses
200

The request has succeeded
Definitions
  • access_token
    • The access token value received after exchanging the authorization token. This field should be passed as Authorization header in API request calls
    • type : string
  • refresh_token
    • You can use this token to refresh an expired access_token.
    • type : string
  • scope
    • Set of scopes allowed by customer and separated by space
    • type : string
  • token_type
    • Type of the access token issued. This is bearer token for authorization_code grant type
    • type : string
  • expires_in
    • Validity of access token in seconds
    • type : number
Example Response for post /authCode/oauth2/token/in/gcb
400

error
invalid_request
invalid_grant
unsupported_grant_type
unauthorized_client
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /authCode/oauth2/token/in/gcb 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
401

error
invalid_client
Definitions
  • error_description
    • Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
    • type : string
  • error
    • If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
    • type : string
    • enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
  • error_uri
    • A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
    • type : string
  • required
    • error
Response Schema for post /authCode/oauth2/token/in/gcb 
{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}
500

server_error
This operation returns no content.