API reference

Project API credentials

Create a project-scoped API key with a user JWT. Copy the secret at issuance; later calls can list, rotate, or revoke the credential.

How it fits together

01Issue an API credential for a project. Returns the secret once
02List the API credentials issued for a project
03Issue a replacement credential and expire the old one after a bounded overlap. Returns the new secret once

Select an action to see its complete inputs, request, response, and status codes.

Issue an API credential for a project. Returns the secret once

POST/api/v1/tenancy/projects/{project_id}/credentials

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`project_id`	Path	string	Required	Mahvash extension	Project ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`attributed_team`	Body	string	Optional	Mahvash extension	Team every request made with this key is charged to. Attribution only - it confers no access.
`expires_at`	Body	string	Optional	Mahvash extension	ISO 8601 timestamp after which the credential stops working.
`name`	Body	string	Required	Mahvash extension	Human-readable label for the credential.
`scopes`	Body	array<value>	Optional	Mahvash extension	Allow-list of scopes. Omit or send an empty list for everything the project allows.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>/credentials' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "production-backend"
}'

Response

{
  "status": 201,
  "data": {
    "credential": {
      "id": "<credential-uuid>",
      "project": "<project-uuid>",
      "name": "Server integration",
      "prefix": "<key-prefix>",
      "status": "ACTIVE"
    },
    "token": "<shown-once-project-api-key>"
  }
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
201	Issue an API credential for a project. Returns the secret once.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

List the API credentials issued for a project

GET/api/v1/tenancy/projects/{project_id}/credentials

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`project_id`	Path	string	Required	Mahvash extension	Project ID.
`search`	Query	string	Optional	Mahvash extension	Case-insensitive search over credential name and public prefix.
`status`	Query	string	Optional	Mahvash extension	Filter by ACTIVE, ROTATING, or REVOKED.
`page`	Query	integer	Optional	Mahvash extension	One-based page number when bounded pagination is requested.
`page_size`	Query	integer	Optional	Mahvash extension	Page size from 1 through 100 when bounded pagination is requested.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>/credentials' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	List the API credentials issued for a project.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Issue a replacement credential and expire the old one after a bounded overlap. Returns the new secret once

POST/api/v1/tenancy/credentials/{credential_id}/rotate

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`credential_id`	Path	string	Required	Mahvash extension	API credential ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/credentials/<credential_id>/rotate' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
201	Issue a replacement credential and expire the old one after a bounded overlap. Returns the new secret once.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Revoke an API credential immediately

DELETE/api/v1/tenancy/credentials/{credential_id}

Production base URLhttps://api.mahvashai.ir

AuthenticationUser access JWT

ResponseMahvash product envelope

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`credential_id`	Path	string	Required	Mahvash extension	API credential ID.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.

Request

curl -X DELETE 'https://api.mahvashai.ir/api/v1/tenancy/credentials/<credential_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Revoke an API credential immediately.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.