Skip to main content
TrayLinx uses JWT Bearer tokens for user authentication. Every API request must include the token in the Authorization header alongside an application-level Api-Key header.

​
Obtaining a Token

Authenticate by posting credentials to the login endpoint. The Auth service returns both an accessToken (short-lived) and a refreshToken (long-lived). 
curl -X POST https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token \n  -H "Content-Type: application/json" \
  -H "Api-Key: <your_api_key>" \
  -d '{
    "username": "[email protected]",
    "password": "your_password"
  }'
Response: 
{
  "data": {
    "id": "user-123",
    "type": "session",
    "attributes": {
      "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
      "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
      "email": "[email protected]",
      "firstName": "Jane",
      "lastName": "Doe"
    }
  }
}
Store both tokens securely. Do not expose them in URLs or logs.

​
Using the Token in Requests

Include the access token as a Bearer credential in the Authorization header of every request: 
curl https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/organizations \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Api-Key: <your_api_key>" \
  -H "Accept: application/json"
Tokens must contain only alphanumeric characters, dots (.), hyphens (-), and underscores (_). Any other characters indicate token corruption and the request is rejected.

​
Refreshing a Token

Access tokens expire. When a request returns 401 Unauthorized, use the refresh token to obtain a new access token without re-entering credentials. 
curl -X POST https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token/refresh \
  -H "Content-Type: application/json" \
  -H "Api-Key: <your_api_key>" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
  }'
Response: 
{
  "data": {
    "id": "user-123",
    "type": "session",
    "attributes": {
      "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
      "refreshToken": "bmV3UmVmcmVzaFRva2Vu..."
    }
  }
}
Replace both the stored access token and refresh token with the new values. Each refresh issues a new refresh token; the old one is invalidated.

​
Token Refresh Flow

  1. Make an API request with the current access token.
  2. If the response is 401 and you have a refresh token, call the refresh endpoint.
  3. On success, update stored tokens and retry the original request.
  4. If the refresh also fails with 401, the session has expired — redirect the user to log in again.

​
Handling 401 Responses

The platform’s axios interceptors implement this flow automatically for browser clients. If you are building a custom integration:
  • Retry a 401 exactly once per request using the refresh token (track with an _retry flag).
  • If the refresh fails, clear stored tokens and require re-authentication.
  • Never retry more than once — this prevents infinite loops on genuinely expired sessions.

​
Revoking a Token (Logout)

Revoke the access token when a user logs out: 
curl https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token/revoke \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Api-Key: <your_api_key>" \
  -H "Accept: application/json"
A 200 response confirms the token is revoked. If you receive 401, the token was already expired. In either case, clear the locally stored tokens.

​
API Key Authentication

The Api-Key header is required on every request in addition to the Bearer token. It identifies the client application: 
Api-Key: <your_api_key>
Obtain your API key from the TrayLinx dashboard. The key is configured via the REACT_APP_AUTH_API_KEY environment variable.
The Api-Key identifies your application; the Authorization: Bearer token identifies the user. Both are required on all requests.

​
Checking Token Info

Verify that an access token is valid and inspect its claims: 
curl https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/token/info \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Api-Key: <your_api_key>"
A 200 response confirms the token is valid. A 401 means it is expired or invalid.

Build docs developers (and LLMs) love

Get started for freeTalk to us