> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.nyotaimara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send and Accept Organization Membership Invitations

> Send a team invitation by email with a role assignment, or exchange an invite token to accept membership. Invitation links expire after 7 days.

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

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer <token>`.
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  The ID of the organization sending the invite. Must match the `:id` path parameter.
</ParamField>

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the organization.
</ParamField>

### Body

<ParamField body="email" type="string" required>
  Email address of the person to invite. The value is lowercased before storage.
</ParamField>

<ParamField body="roleName" type="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](/api/organizations/members).
</ParamField>

### Response

<ResponseField name="success" type="boolean" required>
  `true` on successful dispatch.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message, e.g. `"Invitation sent to jane@example.com."`.
</ResponseField>

<Note>
  Invite tokens are valid for 7 days. If the recipient does not accept within that window, you will need to send a new invite.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "message": "Invitation sent to jane@example.com."
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": "User is already a member of this organization."
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Email and role are required."
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Invalid role selected."
  }
  ```
</ResponseExample>

***

## 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

<ParamField header="Authorization" type="string" required>
  Bearer token of the user accepting the invite. The user must be authenticated before accepting. Format: `Bearer <token>`.
</ParamField>

### Body

<ParamField body="token" type="string" required>
  The invite token extracted from the magic link URL. Found in the `token` query parameter of the invite email link.
</ParamField>

### Response

<ResponseField name="success" type="boolean" required>
  `true` on successful acceptance.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message. Value: `"Successfully joined the organization!"`.
</ResponseField>

<Warning>
  If the token has expired or is invalid, the API returns an error. The recipient must request a new invitation from an organization admin.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.nyotaimara.com/v1/organizations/invites/accept \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "token": "a3f8c2e1d4b6..."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Successfully joined the organization!"
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": "Invalid or expired invitation link."
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "This invitation has expired."
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Invite token is required."
  }
  ```
</ResponseExample>