Skip to main content

Authentication

Our OAuth App API uses the OAuth 2.0 authorization code 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].

We'll create an OAuth App for you and securely send you the app ID, client ID, and secret.

Once your OAuth App has been created, you can redirect users to the following URL to request their consent to access their data:

OAuth Authorization URL (Sandbox)
https://my.dev.firstdollar.com/oauth/app/<your-app-id>/

Receiving the Authorization Code​

After the user has consented, they will be redirected to the redirect URL you provided when requesting access. The redirect will contain a code query parameter that you can exchange for an access token.

Example OAuth Redirect URL
https://example.com/oauth/callback?code=<authorization-code>

Creating an Access Token​

Once you've received an authorization code, you can exchange it for an access token by making a POST request to the /v0/auth/token endpoint using the authorization_code 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.dev.firstdollar.com/v0/auth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<authorization-code>",
  "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 OAuth App API Request (Sandbox)
POST https://api.dev.firstdollar.com/app/<your-app-id>/graphql HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "query": "query { ping }",
  "variables": {}
}
Sample OAuth App 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.dev.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
}

Handling Token Exchange Errors​

If the authorization_code or refresh_token flows fail with an HTTP 401 Unauthorized error, this indicates that the user has either revoked their consent to your OAuth app, or the scopes required by your app have changed since the user's consent was recorded. You'll need to redirect the user to the OAuth login page to re-authenticate. You can do this by redirecting the user back to the OAuth authorization URL.

OAuth Authorization / Reauthorization URL (Sandbox)
https://my.dev.firstdollar.com/oauth/app/:appId/