API Authentication

Authenticate API requests using JWT Bearer tokens.

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": "[e-mail]",
    "password": "your_password"
  }'

Response:

{
  "data": {
    "id": "user-123",
    "type": "session",
    "attributes": {
      "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
      "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
      "email": "[e-mail]",
      "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.