Skip to main content

Authentication

Our Partner API uses the OAuth 2.0 client credentials flow to authenticate clients.

Requesting API Access​

In order to access our APIs, you'll first need to request access by contacting us at [email protected].

Once your access request has been approved, we'll securely send you the client ID and secret.

Creating an Access Token​

Once you've received a client ID and secret, you can exchange them for an access token by making a POST request to the /v0/auth/token endpoint using the client_credentials grant type.

caution

All requests to /v0/auth/token must be made over HTTPS from your backend servers, not your client code, as they require your client_id and client_secret in the request payload.

Sample Token Exchange Request (Sandbox)
POST https://api.sbx.firstdollar.com/v0/auth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<your-client-id>",
  "client_secret": "<your-client-secret>"
}
Sample Token Exchange Response
{
  "access_token": "<access-token>",
  "refresh_token": "<refresh-token>",
  "expires_in": 3600
}

Providing the Access Token on API Requests​

Once you've obtained an access token, you can provide it on API requests by including it in the Authorization header.

Sample Partner API Request (Sandbox)
POST https://api.sbx.firstdollar.com/graphql HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "query": "query { ping }",
  "variables": {}
}
Sample Partner API Response
{
  "data": {
    "ping": "pong"
  }
}

Refreshing an Access Token​

Access tokens expire after one hour. You can generate a new one using the method above or by using the refresh_token grant_type with the refresh token you obtained from a previous call to /v0/auth/token.

Note: both methods generate a new access_token.

Sample Refresh Token Request (Sandbox)
POST https://api.sbx.firstdollar.com/v0/auth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "<your-refresh-token>"
}
Sample Refresh Token Response
{
  "access_token": "<access-token>",
  "refresh_token": "<refresh-token>",
  "expires_in": 3600
}