API Authentication

Overview

This article provides information on the authentication process for API calls.

Each API request made to Fynapse has to be authenticated. Fynapse uses OAuth2 Client Credentials authorization.

The Client Credentials Flow authorization occurs when an application exchanges its application credentials, such as client ID and client secret, for an access token from Fynapse.

The diagram below shows the process of authenticating client credentials using a token:

Requesting Access Token

The access token can be obtained by sending a request to:

https://<instance-url>/auth/token

providing the client id and secret as parameters.

Example request and response below:

1
curl -X POST https://api.fynapse.com/auth/token \
2
     -H "Content-Type: application/x-www-form-urlencoded" \
3
     -d "grant_type=client_credentials" \
4
     -d "client_id=fynapse-client-12345" \
5
     -d "client_secret=s3cr3tK3y!%40%232024"

1
{
2
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
3
  "expires_in": 3600,
4
  "token_type": "Bearer",
5
  "refresh_token": "def50200b1a2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef",
6
  "refresh_expires_in": 86400
7
}

Refreshing the Access Token

The token response includes a refresh_token alongside the access_token. When the access token expires, use the refresh token to obtain a new one instead of starting a new session. Send the request to the same POST /auth/token endpoint with the refresh_token grant type:

$
curl -X POST "https://<instance-url>/auth/token" \
>
  -H "Content-Type: application/x-www-form-urlencoded" \
>
  -d "grant_type=refresh_token" \
>
  -d "refresh_token=<refresh_token>" \
>
  -d "client_id=<client_id>" \
>
  -d "client_secret=<client_secret>"

The client ID and client secret are required for this call, in addition to the refresh token.

The diagram below shows the token refresh process:

The response has the same structure as the initial token response and includes a new refresh token. Two fields define how long the tokens remain valid:

• expires_in - the number of seconds until the access token expires
• refresh_expires_in - the number of seconds until the refresh token expires

Session Timeout

By default, the access token expires 5 minutes (300 seconds) after it is issued, and the refresh token expires after 30 minutes (1800 seconds). Each successful refresh returns a new refresh token, which keeps the session alive. The exact values for your environment are returned in the expires_in and refresh_expires_in fields of the token response.

Errors