Authentication

You use two credentials:

• Your API key, which you create in the dashboard and send to one endpoint only, to get tokens.
• An access token, which you send on every other call. It lasts five minutes.

Get an access tokenCopy Anchor Link

Send the whole key in the X-Api-Key header to Create an access token:

curl -X POST "https://malipo.flex.co.tz/api/v1/oauth/token" \
  -H "X-Api-Key: fpk_test_your_key" \
  -d grant_type=client_credentials

{
  "access_token": "eyJraWQiOiJmbGV4cGF5LTEiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "payments.read payments.write"
}

Then send the token on every other call:

Authorization: Bearer eyJraWQiOiJmbGV4cGF5LTEiLCJhbGciOiJSUzI1NiJ9...

Reuse a token until shortly before expires_in runs out, then get a new one. Getting a token counts against your rate limit.

ScopesCopy Anchor Link

Give each key only the scopes its system needs. Each call needs a particular scope, and a token has all of its key's scopes unless you ask for fewer with the scope parameter.

A call without the scope it needs is refused with 403.

Keeping keys safeCopy Anchor Link

• Keep keys on your server. Never put one in a mobile app, a web page or a repository. Browsers cannot call the API: call it from your server.
• Use one key for each of your systems, such as your web shop and your point of sale, each with only the scopes it needs. Tag payments with metadata to tell your channels apart.
• Restrict a key to your servers' IP addresses. From any other address, getting a token fails with 401, and a call with a token fails with 403.
• Rotate a key if it may have leaked. The old secret keeps working for 60 minutes, or the time you choose.
• Revoke a key you no longer use.

When authentication failsCopy Anchor Link

Getting a token fails with 401 and invalid_client when the key is wrong, disabled, revoked or expired, when you call from outside the key's allowed addresses, or when you use a live key before your merchant is verified.

Every other call fails with 401 when the token is missing, expired or revoked. Get a new token and retry.