# Invitations

An invitation asks a person by email to join the workspace with grants; create, send or withdraw one.

Ids: uuid.

- `GET /workspaces/{workspace_id}/invitations` [List invitations](#list-invitations)
- `POST /workspaces/{workspace_id}/invitations` [Invite a person](#create-invitation)
- `DELETE /workspaces/{workspace_id}/invitations/{id}` [Withdraw an invitation](#delete-invitation)
- `POST /workspaces/{workspace_id}/invitations/{id}/send` [Send an invitation email](#send-invitation)

## Invitation object

An invitation asks a person, by email, to join the workspace with the grants it lists once they accept.

- `id` (uuid, required): The invitation's id.
- `email` (email, required): The email address invited.
- `grants` (array of Grant or null, required): The grants the person holds once they accept, those you are shown.
- `other_grants` (boolean, required): True when the invitation carries a grant you are not shown.
- `created_at` (date-time, required): When the invitation was created.
- `updated_at` (date-time, required): When the invitation last changed.
- `last_sent_at` (date-time or null, required): When the invitation email was last sent; null when it never was.
- `expires_at` (date-time, required): When the invitation stops being valid. Sending it again moves this later.
- `invited_by_user_id` (string or null, required): The user id of the member who sent the invitation. Null when no sender is recorded, when the sender has left, or when you are not shown them.
- `sender_removed` (boolean, required): Whether the recorded sender is no longer a member.

## List invitations

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/invitations`

Preview

Returns the workspace's pending invitations, each with the grants it carries, a page at a time, oldest first. Needs `member.read`; you see the invitations whose grants your reach contains, and every one you sent.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `admin:read`, `admin:write`
- Privilege: `member.read`

Needs `member.read`. `member.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.

### Behavior

- Retry: Safe to send again
- Paging: Cursor · 1000 a page by default, up to 5000

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `email` (string): Only invitations to this email address. One you are not shown answers an empty page, as one never sent does. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
- `limit` (integer): How many invitations a page holds: 1 to 5000, 1000 by default.
  Default: `1000` · 1 to 5000
- `cursor` (string): The `next_cursor` of the previous page, with the same filters.

### Response (200)

- `invitations` (array of Invitation, required): The pending invitations you are shown, oldest first.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor`, with the same filters, for the next page.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `limit` is not 1 to 5000, or `cursor` cannot be read or was sent with other filters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `member.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Invite a person](https://sparklogs.com/docs/api/reference/invitations.md#create-invitation)
- [Withdraw an invitation](https://sparklogs.com/docs/api/reference/invitations.md#delete-invitation)
- [Send an invitation email](https://sparklogs.com/docs/api/reference/invitations.md#send-invitation)

### Example

List pending invitations

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "invitations retrieved",
  "invitations": [
    {
      "id": "1a7e0000-0000-4000-8000-000000000601",
      "email": "casey.nguyen@example.com",
      "grants": [
        {
          "role_id": "analyst",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000103"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "created_at": "2026-11-08T09:00:00Z",
      "updated_at": "2026-11-08T09:00:00Z",
      "last_sent_at": "2026-11-08T09:00:00Z",
      "expires_at": "2027-02-06T09:00:00Z",
      "invited_by_user_id": "AlexRiveraExampleUserId00001",
      "sender_removed": false
    }
  ],
  "next_cursor": null
}
```

## Invite a person

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/invitations`

Preview

Invites an email address to the workspace with the grants it holds once accepted, or saves a pending invitation again: the one `invitation_id` names, or with `invitation_id` left out the email's own. Sending the same `invitation_id` again saves the same invitation, so a retry is safe. It returns 409 for an email that belongs to a member, whether or not you can see them, for an email with a pending invitation under a different `invitation_id`, and, with `invitation_id` left out, for one whose pending invitation carries grants you may not change. Needs `member.manage`, and each grant must sit inside what you may grant. Saving does not send the email; sending it is its own call.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `member.manage`

Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Read before sending again
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Request body

- `email` (email, required): The email address to invite. Required.
- `grants` (array of GrantRequest, required): The grants the person holds once they accept. An empty list invites with none, which needs `member.manage` over every organization. Required.
- `invitation_id` (uuid or null): The invitation to save again, or the id to give a new one: a UUID, which you may choose. Left out, the email's pending invitation is saved again, or a new one is given a new id. A different id for an email with a pending invitation returns 409.

### Response (200)

- `id` (uuid, required): The id of the row the call created or changed.
- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | `email` is empty, `grants` is left out or null, or a grant names no role. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `email` holds no `@`, `invitation_id` is not a UUID, or a grant names a role the workspace does not have, or a malformed scope. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | The grants reach beyond what you may grant, `grants` is empty and you do not hold `member.manage` over every organization, or the invitation saved again carries grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | `invitation_id` names an invitation of another workspace, or one you cannot see. | No |
| 409 | `APP_API_ERR_INVITATION_EMAIL_TAKEN` | The email belongs to a member, whether or not you can see them, a deleted account still in the workspace included; or it has a pending invitation and the body names a different `invitation_id`, or names none and that invitation carries grants you may not change. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List invitations](https://sparklogs.com/docs/api/reference/invitations.md#list-invitations)
- [Withdraw an invitation](https://sparklogs.com/docs/api/reference/invitations.md#delete-invitation)
- [Send an invitation email](https://sparklogs.com/docs/api/reference/invitations.md#send-invitation)

### Example

Invite a person as an analyst for Oakridge Medical

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "casey.nguyen@example.com",
    "grants": [
      {
        "role_id": "analyst",
        "scope": {
          "kind": "selected",
          "org_ids": [
            "0a9e0000-0000-4000-8000-000000000103"
          ]
        }
      }
    ],
    "invitation_id": "1a7e0000-0000-4000-8000-000000000601"
  }'
```

Response (200)

```json
{
  "message": "invitation saved",
  "id": "1a7e0000-0000-4000-8000-000000000601"
}
```

## Withdraw an invitation

`DELETE https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/invitations/{id}`

Preview · Destructive

Withdraws a pending invitation, so it can no longer be accepted. Needs `member.manage`, and the invitation's grants must sit inside your reach.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `member.manage`

Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The invitation's id.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | The invitation carries grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such pending invitation, or one you cannot see. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List invitations](https://sparklogs.com/docs/api/reference/invitations.md#list-invitations)
- [Invite a person](https://sparklogs.com/docs/api/reference/invitations.md#create-invitation)
- [Send an invitation email](https://sparklogs.com/docs/api/reference/invitations.md#send-invitation)

### Example

Withdraw an invitation

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "invitation deleted"
}
```

## Send an invitation email

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/invitations/{id}/send`

Preview

Sends, or sends again, the email of a pending invitation, and moves its expiry 90 days out. Needs `member.manage`. Each API token may send 500 every 5 minutes, and a signed-in person 5 every 30 seconds; a send past that returns 429 with `Retry-After`.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `admin:write`
- Privilege: `member.manage`

Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Read before sending again
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The invitation's id.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_BEYOND_OWN_AUTHORITY` (cause `token_scope`) | The invitation carries grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such pending invitation in the workspace, checked before your privilege. | No |
| 409 | `APP_API_ERR_CONFLICT` | The invitation was declined. | Read first |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `send_limit`) | You sent more invitations than the send limit allows (`cause` `send_limit`); `Retry-After` says when to try again. | After `Retry-After` |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List invitations](https://sparklogs.com/docs/api/reference/invitations.md#list-invitations)
- [Invite a person](https://sparklogs.com/docs/api/reference/invitations.md#create-invitation)
- [Withdraw an invitation](https://sparklogs.com/docs/api/reference/invitations.md#delete-invitation)

### Example

Send the invitation email

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "sent invitation"
}
```

## Grant object

A grant gives one member, group or workspace token one role over a scope: every organization, selected organizations and everything below them, or the workspace itself.

- `id` (uuid): The grant's id; left out on a grant an invitation will become.
- `role_id` (string, required): The role the grant gives.
- `scope` (Scope, required): Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Your own grants show whole. Changing or removing a grant with `inherited` or `other_orgs` needs access over organizations you cannot see; without it the call returns 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`.

## Scope object

- `kind` (one of the values below, required): Which organizations. Required.
  - `all`: Every organization, those added later included.
  - `selected`: The organizations in `org_ids` and everything below them.
  - `workspace`: The workspace itself, no organization.
- `org_ids` (array of uuid): With selected, the topmost organizations you can see, sorted; empty otherwise. Every answer sends it. On a write, the organizations it covers: at least one with selected, none otherwise.
- `inherited` (boolean): True when one of `org_ids` sits below an organization the scope names that you cannot see. Read-only: every answer sends it, and a write ignores it.
- `other_orgs` (boolean): True when the scope covers organizations you cannot see, which are left out without an id or a count; with all, when you cannot see every organization. Read-only: every answer sends it, and a write ignores it.

## GrantRequest object

- `role_id` (string, required): The role the grant gives. Required.
- `scope` (Scope, required): Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Required.

---

Source: <https://sparklogs.com/docs/api/reference/invitations>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
