Note: Skip this step if you already created an app and have a pair of Client ID and Client Secret.

  1. Sign in to developer.citi.com
  2. Select My Applications tab.
  3. Click Register a New App
     


 

a. Fill out the required details

b. Upload an icon for your app (optional)

c. Click Submit

d. You will receive a pair of Client ID and Client Secret. Store this information securely. Use the Show button/checkbox to see your Client ID and Client Secret.

Note: Client secret is shown only once, so make sure you save this information. If in any case you lose your credential set, you can use the Regenerate button to get a new set of Client ID & Client Secret.

,

An access token is required to call all the functional APIs. Determine the grant type of an API from its documentation and refer to corresponding section. Note that in order to fully secure the production API environment, mutual authentication using two way TLS is implemented and set up as part of onboarding process.

,

For customer context APIs, this approach (also known as the 3-Legged OAuth) is the most popular.

First, Citi customers are redirected to Citi’s Authorize service, where they are prompted to log in with their User ID and password. By logging in, Citi customers give consent to clients. Next, Authorize will return an authorization code to clients, which can be exchanged for an access_token.

Step 1: Retrieve Authorization Code


This process starts with your app initiating a session with the below URI resource. The URI needs to be opened in user’s web browser. In-app browser can be used for mobile app, but not embedded web view for security reason. As part of the request, you need to send your Client ID and few other required fields.


 

Note: Valid choices for the scope parameter can be found in the country specific resources provided on the portal. Common examples include pay_with_points, accounts_details_transactions, and customers_profiles.

Note: The state parameter is extremely important for preventing cross-site request forgery. It should be a value provided by an opaque data type and be used in your application to maintain state between the request and callback.

GET /authCode/oauth2/authorize
 

https://sandbox.apihub.citi.com/gcb/api/authCode/oauth2/authorize
?response_type=responseType_example
&client_id=clientId_example
&scope=scope_example
&countryCode=countryCode_example
&businessCode=businessCode_example
&locale=locale_example
&state=opaqueStateValue
&redirect_uri=redirectUri_example


Above request opens up a Login page hosted at Citi where the users of your app can log in with their Citibank Online credentials. Once the user has authorized your app to access their account information, you will get an Authorization Code in the response. The code is sent in the query string and is appended to the redirect URI that was provided.

For example, if the redirect URI is https://www.example.com, then the code will be sent to the following URL:

https://www.example.com/?code=theAuthorizationCode&state= opaqueStateValue 


This authorization code is valid for a very short period of time (30 seconds) and should be immediately exchanged for access token.

 

Step 2: Retrieve Access Token


Use the Authorization Code received to exchange with an access token using below URI resource. This API request will require your Client ID and your Client Secret to be sent in a Base64 encoded form as the Authorization request header.

An example of this format is:
 

Base64(client_id:client_secret) 

* POST /authCode/oauth2/token/us/gcb
*Note the country code and set accordingly.

POST https://sandbox.apihub.citi.com/gcb/api/authCode/oauth2/token/us/gcb
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=theAuthorizationCode
&redirect_uri=https://www.google.com.sg/


When successful, the service will respond with the following:
 

access_token

The access token value received after exchanging the authorization token. This field should be passed as Authorization header in API request calls.

refresh_token

Use this token to refresh an expired access_token (see below).

scope

Set of scopes allowed by customer and separated by space.

token_type

Type of the access token issued. This is bearer token for authorization_code grant

expires_in

Validity of access token in seconds.


Example:

 {
   "token_type": "bearer",
   "access_token": "theAccessToken",
   "expires_in": 1800,
   "scope": "accounts_details_transactions",
   "refresh_token": "theRefreshToken"
}


The access token can then be used to access functional APIs. The validity period of access tokens will be determined as part of the onboarding process.

 

Step 3: Refresh as Necessary


If your access token has expired and you still have a valid refresh token, you can exchange it for a new set of valid access and refresh tokens. This API request will require your Client ID and your Client Secret delimited with a colon to be sent in a Base64 encoded form as the Authorization request header.

An example of this format is:

 Base64(client_id:client_secret)

POST /authCode/oauth2/refresh

POST https://sandbox.apihub.citi.com/gcb/api/authCode/oauth2/refresh
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

refresh_token=theRefreshToken&grant_type=refresh_token


When successful, the service will respond with the following:
 

access_token

The access token value received after exchanging the authorization token. This field should be passed as Authorization header in API request calls.

refresh_token

Use this token to refresh an expired access_token (see below).

scope

Set of scopes allowed by customer and separated by space.

token_type

Type of the access token issued. This is bearer token for authorization_code grant

expires_in

Validity of access token in seconds.

 

Example:

 {
   "token_type": "bearer",
   "access_token": "theAccessToken",
   "expires_in": 1800,
   "scope": "accounts_details_transactions",
   "refresh_token": "theRefreshToken"
}


The refreshed access token can then be used to access functional APIs. The validity period and maximum number of refresh tokens will be determined as part of the onboarding process.

Step 4: Revoke


If access token is no longer required, you can revoke it. The revoke call will terminate the access granted by a Citi customer to your application. This API request will require your Client ID and your Client Secret delimited with a colon to be sent in a Base64 encoded form as the Authorization request header.

An example of this format is:
 

 Base64(client_id:client_secret)


The token type hint is optional to assist with the token lookup; values are access_token or refresh_token.

POST /authCode/oauth2/revoke

POST https://sandbox.apihub.citi.com/gcb/api/authCode/oauth2/revoke
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

token=theToken&token_type_hint=refresh_token

When successful, the service will respond with a status of the token revocation request.

,

When you are trying to access resources not protected by customer credentials, you can request an access token using only your client credentials.

Our APIs Pay with Points and Onboarding use this approach. This API request will require your Client ID and your Client Secret delimited with a colon to be sent in a Base64 encoded form as the Authorization request header.

An example of this format is:

 Base64(client_id:client_secret)

POST /clientCredentials/oauth2/token/us/gcb

POST https://sandbox.apihub.citi.com/gcb/api/clientCredentials/oauth2/token/us/gcb
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=/api

 

When successful, the service will respond with the following:
 

access_token

The access token value received after exchanging the authorization token. This field should be passed as Authorization header in API request calls.

scope

Set of scopes granted and separated by space.

token_type

Type of the access token issued. This is bearer token for client_credentials grant.

expires_in

Validity of access token in seconds.


Example:

{
   "token_type": "bearer",
   "access_token": "theAccessToken",
   "expires_in": 1800,
   "scope": "/api"
}

The access token can then be used to access functional APIs that do not require customer credentials. The validity period of access tokens will be determined as part of the onboarding process.

,

Only selected partners can obtain an access_token via this approach. If you’d like to be considered for this approach, please drop us an email.

,

Kindly refer to following test user credentials in sandbox:

Username Password
SandboxUser1 P@ssUser1$
SandboxUser2 P@ssUser2$
SandboxUser3 P@ssUser3$
SandboxUser4 P@ssUser4$
SandboxUser5 P@ssUser5$
,

Trying to test and see what our APIs are all about quickly? We understand! The first thing you’ll need to make Citi API calls is an Access Token. Use the below tool to generate an Access Token quickly without implementing a full OAuth 2.0 flow. You can then use this token to call other APIs on our platform, either through their inline testing tools, an API testing tool, or your own application. When you’re ready to do a full integration, take a look at our Authorize documentation!

Test Credentials
An Access Token not only identifies you as an application publisher to Citi, but also identifies your end user so you can access their data with their consent. See the table below for the sample accounts and data that we offer in our sandbox. Once you generate an Access Token, you can use it to access the sample data for that sample user.

S.No Username
1 SandboxUser1
2 SandboxUser2
3 SandboxUser3
4 SandboxUser4
5 SandboxUser5

Step 1: Choose Your Grant Type

There are two Grant Types: 2-Legged (Client Credentials) and 3-Legged (Authorization Code). If you need to get data or perform transactions on behalf of a specific user, you will want to use 3-Legged (for example, to use our Accounts or Money Movement APIs). If you need to simply access Citi services without a specific user in mind, you will want to use 2-Legged (for example, to use our Pay With Points or Onboarding APIs).

Step 2: Select App

If you haven’t created an application yet, make sure to go to app page to create a new Client ID and Client Secret. Copy these down in a separate document and paste them below. You will use your Client ID and Client Secret for identifying yourself to Citi for all API calls.

Client ID: This can be grabbed from your applications page.

Client Secret: This is generated from your applications page when you first create your application. You can reset it from the applications page – but keep in mind there will be a delay before you can make a successful API call after you reset your client secret.

Step 3: Choose Test Profile

If you are generating an Access Token for 3-Legged OAuth, select the user for which you are generating the Access Token. This determines which test data set you will receive when you use your token for further test API calls.

Step 4: Generate Access Token

Click the button below to generate your access token.

Generate Token

Your Access Token

Response Status Code

 
Response Headers

 
Response Body