Authentication

Every authenticated request sends Authorization: Bearer <token>. The token is one of two very different things:

The rule of thumb: your software uses project API keys; people use JWTs. A background service that drafts support replies should hold a project key. An administrator creating that service's project and key does so as themselves, with a JWT, so the audit trail names them.

Each endpoint in the API reference states which credential it accepts. AI endpoints under /v1 accept either; workspace management under /api/v1/tenancy and webhook management require a user JWT.

People sign in with their phone number and a one-time code. A successful verification returns an access token and a refresh token:

# 1. Ask for a one-time code (sent by SMS to the phone number)
curl -X POST https://api.mahvashai.ir/api/v1/users/register/ \
  -H "Content-Type: application/json" \
  -d '{"phone": "09XXXXXXXXX"}'

# 2. Verify the code and receive a token pair
curl -X POST https://api.mahvashai.ir/api/v1/users/register/auth/ \
  -H "Content-Type: application/json" \
  -d '{"phone": "09XXXXXXXXX", "otp": "<code>"}'

The first successful sign-in for a phone number creates the account (created: true) together with a personal organization and a default project, so the new user can make requests immediately.

Access tokens expire. When a request answers 401, exchange the refresh token for a new pair:

curl -X POST https://api.mahvashai.ir/api/v1/users/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "<user-refresh-jwt>"}'

• A refresh token is single-use: store the new pair and discard the old one.
• Only a 401 from the refresh endpoint means the session is over. A 409 refresh_token_rotated means another request already rotated the same token moments ago; a 429 or 503 is temporary. In those cases keep the tokens and retry shortly.
• Refresh from one place at a time. Two concurrent refreshes with the same token cannot both win.

Keys are issued for a specific project by a person who is an administrator of it. You can do it in the dashboard or through the API:

curl -X POST https://api.mahvashai.ir/api/v1/tenancy/projects/<project-uuid>/credentials \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "scopes": ["models.request", "chat.read"],
    "expires_at": "2027-06-30T00:00:00Z"
  }'

• name (required) is a human label. Name keys after the system and environment that use them.
• scopes narrows what the key may do. Omit it or send [] for everything the project allows.
• expires_at makes the key stop working at a fixed time — useful for contractors or temporary tests.
• attributed_team charges the key's usage to a team for reporting. It is a label only and grants no access.

The response contains token exactly once. Copy it straight into your secret store. The prefix (for example mk_1a2b3c4d5e6f) is the public half: safe to log and enough to identify or revoke the key later.

Then send the key as a bearer token:

curl https://api.mahvashai.ir/v1/responses \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "input": "Ping"}'

Scopes limit a key to the operations a particular system needs. A key that only drafts replies does not need to delete files.

• A *.write scope includes its matching *.read scope, so a key that creates vector stores can read them back.
• models.request does not include reading history. A key that sends prompts and reads stored conversations needs models.request and chat.read.
• An unknown scope is rejected when the key is issued, never silently ignored — a typo can never produce a key with more reach than you intended.

Whatever its scopes and whoever created it, a project key cannot perform organization administration. The following are refused to every key:

• inviting, removing or changing the role of members;
• managing teams and project access grants;
• issuing, rotating or revoking API keys;
• managing webhook subscriptions;
• reading the audit trail or organization-wide usage reports, or anything related to the wallet.

A key also acts with the live permissions of the person who issued it, in its project — never more. If that person's role is lowered, the key's reach shrinks with it. If that person is removed from the organization or suspended, every key they issued is revoked in the same moment, and it stays revoked even if they later rejoin. Plan for this: when a teammate who owns an integration leaves, issue a replacement key from another administrator before removing them.

Finally, a key is pinned: it always works in its own organization and project. A request that sends a different X-Mahvash-Organization or X-Mahvash-Project is refused instead of being quietly redirected.

Treat keys like passwords with a lifecycle:

# Planned replacement: the old key keeps working during the overlap window
curl -X POST https://api.mahvashai.ir/api/v1/tenancy/credentials/<credential-uuid>/rotate \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme"

# Suspected leak: stop the key immediately
curl -X DELETE https://api.mahvashai.ir/api/v1/tenancy/credentials/<credential-uuid> \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme"

• Rotate for planned replacement. You receive a new token, and the old one keeps working for an overlap window (24 hours by default) so you can deploy the new key without downtime.
• Revoke when a key may have leaked. It stops working immediately.

Revoked keys remain visible in the key list so an investigation can see when a key existed and when it was stopped. To know whether a key works right now, read its usable field: a key can be ACTIVE and already expired.

• Keep keys and tokens on trusted servers only, in environment variables or a secret manager.
• Never put a key or token in browser code, mobile app packages, URLs or query strings, logs, analytics events, screenshots, or public repositories.
• Use one key per system and environment, so you can revoke one without breaking the rest.
• Give each key the smallest set of scopes it needs and an expiry when the use is temporary.
• Log the X-Request-ID and the key prefix when you need to trace a call — never the key itself.