Authentication

Learn how to connect to Flutterwave Servers.

Flutterwave utilizes OAuth2.0 to authenticate API requests. Using OAuth 2.0, You can connect your application to our servers without using your keys or sensitive information. This guide explains how to generate and use tokens to authenticate your requests.

Using OAuth2.0

To authenticate your API requests with OAuth2, you'll need to generate an acces_token by sending a POST request to the [Oauth2 endpoint] by passing it the client_id, client_secret, and grant_type.

cURL

curl -X POST 'https://keycloak.dev-flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials'

On a successful request, you’ll get a response with access_token, expires_in, token_type, not-before-policy, and scopes.

Here is an example response:

JSON

{
    "access_token": "SAMPLE_TOKEN",
    "expires_in": 600,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

Next, you can make requests using the access token to any of our endpoints.

cURL

# Sample cURL request to the payment gateway's API endpoint
curl -X GET https://api.flutterwave.com/v4/endpoint \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json"

🚧

Your access token enables several actions on your Flutterwave account. Keep it confidential and store it only on your servers, ideally as an environment variable. Exclude it from your Git repository and front-end JavaScript code.

Refreshing Your Access Token

Your token expires periodically to protect you from security risks. This means the token may expire even while your session remains active. Each token lasts for 10 minutes (with expires_in indicating the remaining time) and should be refreshed regularly to maintain access.

As a rule of thumb, you should refresh your token using the same endpoint before the expires_in time elapses. For example, you can implement a check that ensures the token refreshes at least 1 minute before expiration.

JavaScript

const axios = require('axios');

let accessToken = null;
let expiresIn = 0; // token expiry time in seconds
let lastTokenRefreshTime = 0;

async function refreshToken() {
  try {
    const response = await axios.post(
      'https://keycloak.dev-flutterwave.com/realms/flutterwave/protocol/openid-connect/token',
      new URLSearchParams({
        client_id: '<CLIENT_ID>',
        client_secret: '<CLIENT_SECRET>',
        grant_type: 'client_credentials'
      }),
      {
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
      }
    );

    accessToken = response.data.access_token;
    expiresIn = response.data.expires_in;
    lastTokenRefreshTime = Date.now();

    console.log('New Token:', accessToken);
    console.log('Expires in:', expiresIn, 'seconds');
  } catch (error) {
    console.error('Error refreshing token:', error.response ? error.response.data : error.message);
  }
}

async function ensureTokenIsValid() {
  const currentTime = Date.now();
  const timeSinceLastRefresh = (currentTime - lastTokenRefreshTime) / 1000; // convert to seconds
  const timeLeft = expiresIn - timeSinceLastRefresh;

  if (!accessToken || timeLeft < 60) { // refresh if less than 1 minute remains
    console.log('Refreshing token...');
    await refreshToken();
  } else {
    console.log(`Token is still valid for ${Math.floor(timeLeft)} seconds.`);
  }
}

// Example usage: Call `ensureTokenIsValid` before making API requests
setInterval(ensureTokenIsValid, 5000); // check every 5 seconds