Skip to main content
Organization invitations are delivered by email as magic links. When you send an invite, Nyota Imara generates a secure token, stores it, and emails a 7-day link to the recipient. The recipient accepts the invite by exchanging the token via the API while authenticated.

​
Send an invitation

Invites a user to join the organization. If the email address already belongs to an active member, the request is rejected with 409 Conflict.

​
Endpoint

POST https://api.nyotaimara.com/v1/organizations/:id/invites

​
Headers

​
Authorization
string
required
Bearer token. Format: Bearer <token>.
​
X-Organization-Id
string
required
The ID of the organization sending the invite. Must match the :id path parameter.

​
Path parameters

​
id
string
required
The unique identifier of the organization.

​
Body

​
email
string
required
Email address of the person to invite. The value is lowercased before storage.
​
roleName
string
required
Role to assign when the invite is accepted. Built-in values: "owner", "admin", "billing", "member". You can also pass the name of a custom role created via the roles endpoints.

​
Response

​
success
boolean
required
true on successful dispatch.
​
message
string
Confirmation message, e.g. "Invitation sent to jane@example.com.".
Invite tokens are valid for 7 days. If the recipient does not accept within that window, you will need to send a new invite.
curl --request POST \
  --url https://api.nyotaimara.com/v1/organizations/org_01j9kxyz/invites \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: org_01j9kxyz' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "jane@example.com",
    "roleName": "admin"
  }'

{
  "success": true,
  "message": "Invitation sent to jane@example.com."
}

​
Accept an invitation

Exchanges an invite token to complete membership. The token is consumed on acceptance — clicking the link again does nothing.

​
Endpoint

POST https://api.nyotaimara.com/v1/organizations/invites/accept

​
Headers

​
Authorization
string
required
Bearer token of the user accepting the invite. The user must be authenticated before accepting. Format: Bearer <token>.

​
Body

​
token
string
required
The invite token extracted from the magic link URL. Found in the token query parameter of the invite email link.

​
Response

​
success
boolean
required
true on successful acceptance.
​
message
string
Confirmation message. Value: "Successfully joined the organization!".
If the token has expired or is invalid, the API returns an error. The recipient must request a new invitation from an organization admin.
curl --request POST \
  --url https://api.nyotaimara.com/v1/organizations/invites/accept \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "token": "a3f8c2e1d4b6..."
  }'

{
  "success": true,
  "message": "Successfully joined the organization!"
}