Skip to main content
Mutasib secures every API request with an API token. Generate a token from your Mutasib dashboard, pick an expiration of 30, 60, or 90 days, and attach it to every request as an Authorization: Bearer header. All programmatic access to the API uses API tokens.
API tokens are not available on a free trial. An active paid plan is required to create and use them.

​
Getting a token

  1. Sign in to your Mutasib dashboard.
  2. Open the API tokens section.
  3. Create a new token, choose an expiration of 30, 60, or 90 days, and copy the token immediately. Tokens are shown only once at creation time.
  4. Store the token in a secure secret store (encrypted keystore, environment variable, or secrets manager).
  5. Revoke a token anytime from the same section of the dashboard. Once a token expires or is revoked, requests using it return 401 Unauthorized.

​
Using your token

Pass the token in the Authorization header on every request. The value must be prefixed with Bearer (note the space).

​
Example

​
Scope (allowlist)

API tokens are restricted to a fixed set of path prefixes. Requests to any path outside this list return 404 Not Found. Everything else returns 404 Not Found. All other /ai/* sub-paths are outside the API scope.

​
Plan gating

Some features are available only on specific plans. If your token belongs to a shop that doesn’t include a feature (for example, an AI endpoint on a Starter plan), the API returns 403 Forbidden with a detail message explaining the required plan. The same gating applies inside the Mutasib dashboard, so a user who cannot reach a feature there also cannot reach it through the API. Pro-only features currently include AI demand prediction, AI reorder suggestions, supplier management, and credit notes. Inspect the plan_features object on the shop response to detect available capabilities at runtime.

​
HTTP error codes

When authentication fails, the API returns a standard HTTP error code. The table below lists the codes you will encounter most often and what to do about each.
Treat your API token like a password. Store it in a secure, persistent location such as an encrypted keystore, environment variable, or secrets manager. Never embed tokens in URLs, log files, or client-side source code. If you suspect a token has been compromised, revoke it from the dashboard and generate a new one.