Authentication | Citi Docs Demo

Overview

Citi Consumer APIs use OAuth 2.0 to authenticate your application and authorize access to a customer’s data. Every request must include a valid access token, and every token carries the specific scopes the customer has consented to — so your app only ever sees what it is permitted to see.

There are two flows depending on what you are building:

Client credentials — for server-to-server calls that don’t act on behalf of a specific customer (for example, product catalog or rate lookups).
Authorization code — for accessing an individual customer’s accounts, cards, and payments after they sign in and grant consent.

Getting an access token

Register your application

Create an app to receive your client_id and client_secret. Register the redirect URIs your customers will return to after granting consent.

Exchange the code for a token

Send the authorization code to the token endpoint to receive an access_token and a refresh_token.

Call the API

Include the access token as a bearer token on every request: Authorization: Bearer {access_token}

curl -X POST https://api.citi.com/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback"

Scopes

Request the narrowest set of scopes your experience needs. Customers see exactly what they are approving.

Scope	Grants access to
`accounts:read`	Deposit account details, balances, and transactions
`cards:read`	Credit and debit card details and activity
`cards:manage`	Card controls such as lock/unlock and travel notices
`payments:write`	Send money, bill pay, and transfers
`rewards:read`	ThankYou® points balance and redemption options

Access tokens are short-lived. Use the refresh_token to obtain a new access token without prompting the customer to sign in again.

Keeping tokens secure

Never expose your client_secret or a customer’s tokens in client-side code, URLs, logs, or version control. Store tokens encrypted at rest and transmit them only over TLS 1.2+.

Rotate your client secret periodically and immediately if it is ever exposed.
Scope tokens to the minimum access your feature requires.
Revoke a refresh token as soon as a customer disconnects your app.

Ready to make your first call? Head to the Deposit Accounts guide.