API reference

Invitations

Invite a user into an organization, then let the recipient accept or reject. Invitation management and recipient actions use different scopes.

How it fits together

01Invite an identity to the organization and return its public ID
02Accept an invitation by ID as its authenticated target
03Reject an invitation by ID as its authenticated target

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

Invite an identity to the organization and return its public ID

POST/api/v1/tenancy/invitations

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
`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.
`identity`	Body	string	Required	Mahvash extension	Phone number of the person being invited. Normalized before storage.
`role`	Body	string	Optional	Mahvash extension	Organization role: owner, admin, member, or viewer. Never above the caller's own.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/invitations' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "identity": "09120000000"
}'

Response

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

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

Status codes

HTTP	Details
201	Invite an identity to the organization and return its public ID.
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.

Accept an invitation by ID as its authenticated target

POST/api/v1/tenancy/invitations/{invitation_id}/accept

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
`invitation_id`	Path	string	Required	Mahvash extension	Invitation 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/invitations/<invitation_id>/accept' \
  -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	Accept an invitation by ID as its authenticated target.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
404	No such resource is visible to this principal.
429	A quota or rate limit was exceeded.
500	An internal error occurred.

Reject an invitation by ID as its authenticated target

POST/api/v1/tenancy/invitations/{invitation_id}/reject

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
`invitation_id`	Path	string	Required	Mahvash extension	Invitation 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/invitations/<invitation_id>/reject' \
  -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	Reject an invitation by ID as its authenticated target.
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 open invitation

DELETE/api/v1/tenancy/invitations/{invitation_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
`invitation_id`	Path	string	Required	Mahvash extension	Invitation 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/invitations/<invitation_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 open invitation.
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 invitations for the selected organization

GET/api/v1/tenancy/invitations

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
`page`	Query	integer	Optional	Mahvash extension	Bounded tenancy-list page query parameter.
`page_size`	Query	integer	Optional	Mahvash extension	Bounded tenancy-list page_size query parameter.
`role`	Query	string	Optional	Mahvash extension	Bounded tenancy-list role query parameter.
`search`	Query	string	Optional	Mahvash extension	Bounded tenancy-list search query parameter.
`status`	Query	string	Optional	Mahvash extension	Bounded tenancy-list status query parameter.
`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/invitations' \
  -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 invitations for the selected organization.
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 open invitations addressed to the authenticated account

GET/api/v1/tenancy/invitations/received

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
`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/invitations/received' \
  -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 open invitations addressed to the authenticated account.
401	Authentication credentials are missing or invalid.
403	The principal is not allowed to perform this request.
429	A quota or rate limit was exceeded.
500	An internal error occurred.