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 the read:bank_accounts scope. 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:

$
curl -X POST https://api.givechariot.com/auth/oauth/token \
>
  -u "<client_id>:<client_secret>" \
>
  -d "grant_type=authorization_code" \
>
  -d "code=<authorization_code>" \
>
  -d "redirect_uri=<redirect_uri>"

The response includes an access_token and refresh_token:

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:

$
curl -X POST https://api.givechariot.com/auth/oauth/token \
>
  -u "<client_id>:<client_secret>" \
>
  -d "grant_type=refresh_token" \
>
  -d "refresh_token=<refresh_token>"

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: