FDX Authentication

The FDX API uses OAuth 2.0 Bearer token authentication combined with IP address whitelisting.

Client Setup

To access the FDX API, you need a client name and client secret for each environment. Contact Chariot at support@givechariot.com to request credentials.

Each environment has its own set of credentials. Staging credentials cannot be used in production and vice versa.

OAuth 2.0

All requests must include a valid OAuth 2.0 Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Tokens must include exactly one of the following scopes — they are mutually exclusive per authorization. An authorization containing both will be rejected.

A client may hold both scopes, but each FDX authorization must contain exactly one. Requests without a valid token receive a 401 Unauthorized response.

Token Exchange

The FDX API uses the OAuth 2.0 Authorization Code flow. After receiving client credentials from Chariot, follow these steps to obtain an access token.

OAuth Endpoints

OIDC Well-Known Configuration

1. Authorize

Redirect the user to the authorization endpoint:

GET https://dashboard.givechariot.com/oauth/authorize
  ?client_id=<client_id>
  &redirect_uri=<redirect_uri>
  &response_type=code
  &scope=read:bank_accounts

After the user authorizes, the browser redirects to your redirect_uri with an authorization code query parameter.

2. Exchange code for token

Exchange the authorization code for an access token and refresh token.

POST https://api.givechariot.com/auth/oauth/token

Header — authenticate with HTTP Basic using your client credentials. Requests without this header will be rejected with 403 Unauthorized.

Authorization: Basic base64(client_id:client_secret)

Body (application/x-www-form-urlencoded):

Response:

1
{
2
  "access_token": "...",
3
  "token_type": "Bearer",
4
  "refresh_token": "...",
5
  "scope": "read:bank_accounts"
6
}

3. Refresh token

When the access token expires, use the refresh token to obtain a new one.

POST https://api.givechariot.com/auth/oauth/token

Header — authenticate with HTTP Basic using your client credentials. Requests without this header will be rejected with 403 Unauthorized.

Authorization: Basic base64(client_id:client_secret)

Body (application/x-www-form-urlencoded):

IP Whitelisting

In addition to OAuth 2.0, all requests are validated against an IP whitelist. Requests from non-whitelisted IP addresses receive a 403 Forbidden response.

Contact Chariot to register IP addresses for FDX API access.

Error Responses

All errors follow the RFC 7807 Problem Details format:

1
{
2
  "type": "about:blank",
3
  "title": "Unauthorized",
4
  "status": 401,
5
  "detail": "Missing or invalid Bearer token"
6
}

Token Exchange Errors

Errors returned by POST /auth/oauth/token:

API Request Errors

Errors returned by FDX API endpoints: