Citi Authentication: API Security & Access (2026)

Authentication overview

Citi's API platform, Citi Developer Portal, implements robust authentication mechanisms to secure access to its financial APIs. The core of this security infrastructure relies on the OAuth 2.0 framework, an industry-standard protocol for authorization that allows applications to access user data without exposing user credentials directly. This approach delegates user authentication to the authorization server, which then issues access tokens to the client application. These tokens are used to authorize API requests for a limited duration, enhancing security by reducing the risk associated with persistent credentials.

For developers, understanding the distinction between authorization and authentication is critical. Authentication verifies the identity of a user or client application, while authorization determines what actions that authenticated entity is permitted to perform. Citi's system uses OAuth 2.0 primarily for authorization, granting specific permissions to client applications after they have been authenticated and a user has consented to data access, where applicable. The process involves multiple steps, including client registration, token requests, and token validation, all designed to protect sensitive financial data and ensure compliance with regulatory standards such as PCI DSS and GDPR.

Citi's implementation of OAuth 2.0 is designed to support various integration scenarios, from server-to-server applications requiring direct API access to user-facing applications that need to interact with customer accounts. Each scenario dictates a specific OAuth 2.0 grant type, tailored to provide the appropriate level of security and user experience. The developer portal provides comprehensive guides and examples to facilitate integration, ensuring developers can correctly implement the authentication flows for their applications.

Supported authentication methods

Citi primarily supports OAuth 2.0 for authenticating API requests. This protocol provides secure delegated access to resources, allowing third-party applications to obtain limited access to user accounts on an HTTP service, such as Citi's APIs. The choice of OAuth 2.0 grant type depends on the nature of the client application and the type of access required.

OAuth 2.0 Grant Types

• Client Credentials Grant: This grant type is suitable for confidential client applications capable of maintaining the confidentiality of their client secret. It is used when an application needs to access its own service resources (not a user's) or act on behalf of the service itself. For example, a backend service processing payments would use this flow to access a payment API directly. The application exchanges its client ID and client secret for an access token.
• Authorization Code Grant: This is the most common and recommended grant type for public and confidential clients that need to access user-specific data. It involves redirecting the user to Citi's authorization server to grant permission, after which an authorization code is returned to the client. The client then exchanges this code, along with its client ID and client secret, for an access token and optionally a refresh token. This separation of concerns prevents the client application from ever handling the user's credentials directly.

Other methods, such as API keys or basic authentication, are typically not used as primary authentication mechanisms for production environments due to the enhanced security offered by OAuth 2.0, especially when handling financial transactions and sensitive customer data.

Authentication Methods Table

Getting your credentials

To begin integrating with Citi's APIs, developers must obtain the necessary credentials. This process typically starts with registering an application on the Citi Developer Portal. The registration process generates a unique Client ID and Client Secret, which are fundamental for all OAuth 2.0 authentication flows.

Steps to obtain credentials:

1. Register for a Developer Account: Navigate to the Citi Developer Portal registration page and create an account. This provides access to the sandbox environment and toolkits.
2. Create an Application: Once logged in, locate the 'My Apps' section or similar interface to register a new application. During this process, you will typically need to provide details about your application, such as its name, description, and redirect URIs (for Authorization Code Grant flows).
3. Retrieve Client ID and Client Secret: Upon successful application registration, the portal will generate and display your Client ID and Client Secret. The Client Secret is a highly sensitive credential and should be stored securely. For security reasons, it is often displayed only once or can be regenerated if lost.
4. Configure Redirect URIs: For OAuth 2.0 Authorization Code Grant, it is crucial to configure the exact redirect URIs that your application will use. These URIs must be pre-registered with Citi to prevent redirection attacks.
5. Request Live Environment Access: While the sandbox credentials allow full testing, access to the live production environment requires a formal engagement with Citi sales representatives. This usually involves a more rigorous application review process to ensure compliance and security standards are met for production-grade integrations. Details on this process are available on the Citi pricing and engagement page.

It is important to manage these credentials with the utmost care, treating them like passwords. Never hardcode them directly into publicly accessible code repositories or client-side applications.

Authenticated request example

This example demonstrates how to obtain an access token using the OAuth 2.0 Client Credentials Grant and then use it to make an authenticated API request to a hypothetical Citi API endpoint. This flow is suitable for server-side applications that do not require user interaction.

Step 1: Obtain an Access Token

Send a POST request to Citi's token endpoint with your Client ID and Client Secret. Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual credentials.

curl -X POST \
  https://sandbox.developer.citi.com/api/v1/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

A successful response will return a JSON object containing the access_token, token_type (usually 'Bearer'), and expires_in (token validity duration in seconds).

{
  "access_token": "eyJraWQiOiJmZ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "accounts.read payments.init"
}

Step 2: Make an Authenticated API Call

Once you have the access_token, include it in the Authorization header of your subsequent API requests as a Bearer token. This example calls a hypothetical 'Accounts' API to retrieve account information.

curl -X GET \
  https://sandbox.developer.citi.com/api/v1/accounts \
  -H 'Authorization: Bearer eyJraWQiOiJmZ...' \
  -H 'Content-Type: application/json'

Replace eyJraWQiOiJmZ... with the actual access token obtained in Step 1. The API will validate the token and, if valid and authorized, return the requested data.

Security best practices

Securing your integration with Citi's APIs is paramount to protect sensitive financial data. Adhering to these best practices will help mitigate common security risks:

• Protect Client Secrets: Treat your Client Secret as a highly confidential password. It should never be exposed in client-side code (e.g., JavaScript in a browser) or committed to public version control systems. Store it in secure environment variables or a dedicated secret management service.
• Use HTTPS/TLS for all Communications: Always ensure all communication with Citi's API endpoints and your application's redirect URIs occurs over HTTPS (TLS). This encrypts data in transit, preventing eavesdropping and tampering.
• Validate Redirect URIs: For Authorization Code Grant, register specific and strict redirect URIs with Citi. Your application should only accept redirects to these exact URIs. Any deviation could indicate a potential open redirect vulnerability.
• Implement State Parameter: When using the Authorization Code Grant, generate and validate a unique, unguessable state parameter for each authorization request. This protects against Cross-Site Request Forgery (CSRF) attacks by ensuring the response corresponds to a request initiated by your application. The OAuth 2.0 Security Best Current Practice guidelines from IETF emphasize the importance of the state parameter.
• Securely Store Access and Refresh Tokens: Access tokens are short-lived. Refresh tokens, if used, are long-lived and equally sensitive. Store them securely, encrypted at rest, and transmit them only over secure channels. Avoid storing them in browser local storage or session storage, opting instead for HTTP-only, secure cookies or server-side storage.
• Regularly Rotate Credentials: Periodically rotate your Client Secret and any other API keys or credentials. This limits the window of opportunity for an attacker if a credential is compromised.
• Implement Least Privilege: Request only the necessary API scopes (permissions) for your application. Granting broader access than required increases the risk in case of a breach.
• Error Handling without Leaking Information: Design your application's error handling to avoid leaking sensitive information (e.g., internal server errors, stack traces) in API responses to clients.
• Monitor API Usage: Implement logging and monitoring for API calls, especially failed authentication attempts or unusual request patterns, to detect and respond to potential security incidents promptly.
• Keep Dependencies Updated: Regularly update all libraries, frameworks, and SDKs used in your application to patch known vulnerabilities.

By diligently applying these security measures, developers can build secure and resilient integrations with Citi's financial APIs, safeguarding both their applications and their users' data.