Skip to main content
The Flextell API uses OAuth 2.0 for authentication. Every API request must include a valid bearer token in the Authorization header. You obtain this token by completing the OAuth 2.0 Authorization Code flow.

​
Authorization Code flow

The Authorization Code flow is the standard OAuth 2.0 pattern for server-side applications. It involves two main steps: directing the user to authorize your application, then exchanging the resulting code for tokens.
1

Redirect the user to the authorization URL

Send the user to the Flextell authorization endpoint. Include your client_id, the redirect_uri you registered, the scopes your application needs, and response_type=code:
https://dev.flextell.ai/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=YOUR_SCOPES
The user logs in (if not already) and is shown a consent screen listing the permissions your application is requesting.
2

Receive the authorization code

After the user approves, Flextell redirects them back to your redirect_uri with a short-lived code parameter:
https://your-app.example.com/callback?code=AUTHORIZATION_CODE
This code is single-use and expires quickly. Exchange it for tokens immediately.
3

Exchange the code for tokens

Make a server-side POST request to the token endpoint. Include the authorization code, your credentials, and the same redirect_uri used in step 1:
curl --request POST \
  --url https://dev.flextell.ai/oauth/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=authorization_code" \
  --data "code=AUTHORIZATION_CODE" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  --data "redirect_uri=YOUR_REDIRECT_URI"
The response includes an access_token, a refresh_token, and an expires_in value (in seconds):
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200..."
}

​
Including the token in requests

Pass your access_token in the Authorization header on every API request: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Full example: 
curl --request GET \
  --url https://dev.flextell.ai/api/<endpoint> \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Accept: application/json"
Do not pass the token as a query parameter. Always use the Authorization header.

​
Token expiry and refresh

Access tokens expire after the number of seconds indicated by expires_in (typically 3600 seconds / 1 hour). When an access token expires, use your refresh_token to obtain a new one without requiring the user to re-authorize: 
curl --request POST \
  --url https://dev.flextell.ai/oauth/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=refresh_token" \
  --data "refresh_token=YOUR_REFRESH_TOKEN" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET"
The response follows the same structure as the initial token exchange and includes a new access_token. Some implementations also rotate the refresh_token — always store the latest values returned.
If your refresh token has also expired or been revoked, you must restart the full Authorization Code flow.

​
Authentication errors

When a request fails due to an authentication problem, the API returns a 401 Unauthorized response: 
{
  "error": "unauthorized",
  "message": "Bearer token is missing, invalid, or expired."
}
Common causes:
CauseResolution
Missing Authorization headerAdd Authorization: Bearer YOUR_ACCESS_TOKEN to the request
Token expiredUse your refresh token to obtain a new access token
Malformed tokenEnsure the full token string is included without extra whitespace
Token revokedRe-authenticate the user through the Authorization Code flow

​
Security best practices

Never expose your client_secret in client-side code, public repositories, or logs. It must remain server-side only.
  • Store tokens securely. Keep access tokens and refresh tokens in secure, server-side storage. Do not store them in localStorage, cookies without the HttpOnly flag, or unencrypted databases.
  • Use HTTPS everywhere. All requests to the Flextell API must be made over HTTPS. Never send tokens over plain HTTP.
  • Request only the scopes you need. Limit your authorization request to the minimum scopes required for your application.
  • Rotate refresh tokens. If Flextell returns a new refresh token on each refresh, discard the old one immediately and store the new one.
  • Handle expiry proactively. Track the expires_in value and refresh the access token before it expires rather than waiting for a 401 response.

Quick Start

See a working end-to-end example of the auth flow.

API Reference

Explore available endpoints and their required scopes.