Authenticating your application

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Before you can make any requests to the Adfin API, you must generate an access token to authenticate your requests. Adfin uses OAuth 2.0 for secure authentication and authorisation.

OAuth 2.0 flows supported

• Client credentials flow (for platform-to-platform communication)
• Authorization code flow (for biller authorisation on behalf of your platform)

Authentication in Adfin

Authentication You must supply your client_id and client_secret either in the HTTP Basic Auth header or as form parameters. If you include them in both places, they must match exactly.

How to use Header authentication:

xyz123clientid:secret987654321
→ eHl6MTIzY2xpZW50aWQ6c2VjcmV0OTg3NjU0MzIx

Authorization: Basic eHl6MTIzY2xpZW50aWQ6c2VjcmV0OTg3NjU0MzIx

Request example:

curl -X POST "https://api.staging.adfin.com/api/oauth2/token" \
-H "Authorization: Basic $(echo -n 'YOUR_ID:YOUR_SECRET' | base64)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=client_credentials'

Client credentials flow (Platform Token)

This flow is used when platforms need to access Adfin resources directly.

curl -X POST "https://api.staging.adfin.com/api/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=client_credentials
    &client_id=CLIENT_ID
    &client_secret=CLIENT_SECRET'

Body:

• The body contains the grant_type (set to client_credentials)
• Replace your_client_id and your_client_secret with your credentials.

If successful, Adfin will respond with an access token:

{
  "access_token": "your_access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Generate Authorization code

This flow allows your platform to request an access token after receiving an authorization code from a biller's login session.

• 1. Initial Redirect
• 2. Login
• 3. Authorise Screen

The user will be prompted to login to their account.

Step 1: Redirect biller to Adfin's authorisation page

Redirect the biller to Adfin’s authorisation page by constructing your unique authorisation url:

https://staging.adfin.com/auth/login?&client_id={your_client_id}&scope=invoices%20customers&redirect_uri={your_redirect_uri}&state={random_state_value}

Properties required for oAuth redirect:

Step 2: Handle the callback

After the biller logs in and approves the authorisation, they will be redirected back to the redirect_uri configured in Step 1. Adfin will append a code in the query string, like:

https://your-platform.com/callback?code=[your_authorization_code]&state=random_state_value

Step 3: Exchange the authorization code for tokens

Once you have the authorization code, use this cURL request to exchange it for access and refresh tokens:

Use the same authentication patterns as described at the top of the article: header auth, form parameter authentication.

curl -X POST "https://api.staging.adfin.com/api/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d '{
  "grant_type": "authorization_code",
  "client_id": "{your_client_id}",
  "client_secret": "{your_client_secret}",
  "code": "{authorization_code}", //generated from step 2
  "redirect_uri": "{your_redirect_uri}"
}'

You can now use the access_token to make authorised requests on behalf of the biller (e.g Create customers on behalf of the biller).

Managing Refresh Tokens

Use the refresh token to request a new access token when the current access token expires. This is critical for maintaining session continuity without requiring the biller to log in again. Below is the process and an example cURL command to guide you.

Using refresh tokens

You must use refresh tokens to generate new access tokens and additional refresh tokens.

curl -X POST "https://api.staging.adfin.com/api/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d '{
  "grant_type": "refresh_token",
  "client_id": "{your_client_id}",
  "client_secret": "{your_client_secret}",
  "refresh_token": "{your_refresh_token}"
}'

Token expiry

• access_token: Expires after 1 hour.
• refresh_token: Expires after 30 days.

Error handling

• 401 Unauthorized: The refresh token has expired or is invalid. You will will need to prompt the biller to reauthorize via the Authorization Code Flow.
• 400 Bad request: Incorrect request format or missing required parameters.

Best practices for using refresh tokens

• Token rotation: If the response provides a new refresh token, replace the old one in your system. This helps prevent stale tokens.
• Token storage: Store refresh tokens securely (e.g., encrypted) to protect against token theft.
• Graceful expiry handling: Always handle the expiration of access tokens by using the refresh token to avoid biller login disruptions.