# Grants

A grant gives a member, a group or a workspace token a role over a scope of organizations; give, change and remove them.

Belongs to: [Roles](https://sparklogs.com/docs/api/reference/roles.md)

Ids: uuid.

- `POST /workspaces/{workspace_id}/grants` [Give a grant](#create-grant)
- `PUT /workspaces/{workspace_id}/grants/{id}` [Replace a grant](#update-grant)
- `DELETE /workspaces/{workspace_id}/grants/{id}` [Remove a grant](#delete-grant)
- `POST /workspaces/{workspace_id}/grants/batch` [Change a grantee's grants together](#change-grants)

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

## Give a grant

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

Preview

Gives a member, a group or a workspace token a role over a scope. Needs `grant.write` across the scope and over everything the role reaches; a grant on a group also needs `group.write` there, and one on a workspace token `workspace_token.manage` there and `workspace_token.view` to see the token, which a token holds only with `admin:delegate`. A workspace token never changes its own grants. The grantee must sit inside your reach. A grantee you cannot see gets the same response as one that does not exist. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

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

Needs `grant.write`. `grant.write` 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

- `grantee` (Grantee, required): Who the grant is given to. Required.
- `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.

### 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_BAD_PARAMETERS` | `grantee` names no kind or id, or a grant names a role the workspace does not have, or a malformed scope. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | The grant names no role. | 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 `grant.write`. 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 change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `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` | The grantee is not in the workspace, or not one you can 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

- [Replace a grant](https://sparklogs.com/docs/api/reference/grants.md#update-grant)
- [Remove a grant](https://sparklogs.com/docs/api/reference/grants.md#delete-grant)
- [Change a grantee's grants together](https://sparklogs.com/docs/api/reference/grants.md#change-grants)

### Example

Make Sam an engineer for Lakeside Clinic

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grantee": {
      "id": "SamChenExampleUserId00000002",
      "kind": "user"
    },
    "role_id": "engineer",
    "scope": {
      "kind": "selected",
      "org_ids": [
        "0a9e0000-0000-4000-8000-000000000101"
      ]
    }
  }'
```

Response (200)

```json
{
  "message": "grant created",
  "id": "6a170000-0000-4000-8000-000000000502",
  "cache_clear_status": "ok"
}
```

## Replace a grant

`PUT https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/grants/{id}`

Preview

Replaces a grant's role and scope. Needs `grant.write` over both the grant as stored and as replaced, judged as giving a grant is. A grant you cannot see returns 404, as one that does not exist does. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

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

Needs `grant.write`. `grant.write` 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 grant's id.

### Request body

- `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.

### 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` | `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_BAD_PARAMETERS` | A grant names a role the workspace does not have, or a malformed scope. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | The grant names no role. | 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 `grant.write`. 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 change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `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 grant, or one you cannot see. | No |
| 409 | `APP_API_ERR_LAST_ADMINISTRATOR` | The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first. | 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

- [Give a grant](https://sparklogs.com/docs/api/reference/grants.md#create-grant)
- [Remove a grant](https://sparklogs.com/docs/api/reference/grants.md#delete-grant)
- [Change a grantee's grants together](https://sparklogs.com/docs/api/reference/grants.md#change-grants)

### Example

Extend Sam's grant to Harbor Dental

```bash
curl -X PUT \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "engineer",
    "scope": {
      "kind": "selected",
      "org_ids": [
        "0a9e0000-0000-4000-8000-000000000101",
        "0a9e0000-0000-4000-8000-000000000105"
      ]
    }
  }'
```

Response (200)

```json
{
  "message": "grant replaced",
  "id": "6a170000-0000-4000-8000-000000000502",
  "cache_clear_status": "ok"
}
```

## Remove a grant

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

Preview · Destructive

Removes a grant. Needs `grant.write` over it, judged as giving it is. It removes the whole grant; to drop one organization from a `selected` grant, update it with the rest. A grant you cannot see returns 404, as one that does not exist does, and so does a repeat once it is gone: treat that as done. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

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

Needs `grant.write`. `grant.write` 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 grant'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 `grant.write`. 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 change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `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 grant, or one you cannot see. | No |
| 409 | `APP_API_ERR_LAST_ADMINISTRATOR` | The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first. | 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

- [Give a grant](https://sparklogs.com/docs/api/reference/grants.md#create-grant)
- [Replace a grant](https://sparklogs.com/docs/api/reference/grants.md#update-grant)
- [Change a grantee's grants together](https://sparklogs.com/docs/api/reference/grants.md#change-grants)

### Example

Remove Sam's grant

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "grant deleted",
  "cache_clear_status": "ok"
}
```

## Change a grantee's grants together

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

Preview · Destructive

Removes, changes and adds a grantee's direct grants in one transaction: every change is judged as the single-grant calls judge it, and any refusal writes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.

### Access

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

Needs `grant.write`. `grant.write` 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

- `grantee` (Grantee, required): Whose grants change. Required.
- `remove` (array of uuid or null): The ids of the grants to remove.
- `update` (array of GrantUpdate or null): The grants to change, each by id.
- `add` (array of GrantRequest or null): The grants to add.

### Response (200)

- `removed` (array of uuid, required): The ids of the grants removed.
- `updated` (array of uuid, required): The ids of the grants changed.
- `added` (array of uuid, required): The ids of the grants added, in the order add named them.
- `cache_clear_status` (one of the values below, required): How far the change got into every region's cache.
  - `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_BAD_PARAMETERS` | `grantee` is malformed, a grant id comes twice across `remove` and `update`, or a grant names a role the workspace does not have, or a malformed scope. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | `remove`, `update` and `add` are all empty, or a grant names no role. | 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 `grant.write`. 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 change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `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` | The grantee, or a grant in `remove` or `update`, is missing, belongs to another grantee or is outside your reach; `parameter` names it. | No |
| 409 | `APP_API_ERR_LAST_ADMINISTRATOR` | The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first. | 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

- [Give a grant](https://sparklogs.com/docs/api/reference/grants.md#create-grant)
- [Replace a grant](https://sparklogs.com/docs/api/reference/grants.md#update-grant)
- [Remove a grant](https://sparklogs.com/docs/api/reference/grants.md#delete-grant)

### Example

Swap a group's grant for a wider one

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/batch" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [
      {
        "role_id": "analyst_no_raw_logs",
        "scope": {
          "kind": "all",
          "org_ids": []
        }
      }
    ],
    "grantee": {
      "id": "9a0b0000-0000-4000-8000-000000000401",
      "kind": "group"
    },
    "remove": [
      "6a170000-0000-4000-8000-000000000503"
    ]
  }'
```

Response (200)

```json
{
  "message": "grants changed",
  "removed": [
    "6a170000-0000-4000-8000-000000000503"
  ],
  "updated": [],
  "added": [
    "6a170000-0000-4000-8000-000000000505"
  ],
  "cache_clear_status": "ok"
}
```

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

## Grantee object

- `kind` (one of the values below): What kind of grantee `id` names.
  - `user`: A member.
  - `group`: A group.
  - `workspace_key`: A workspace token.
- `id` (string): The member's user id, the group's id or the workspace token's id.

## GrantUpdate object

- `id` (uuid, required): The grant to change. Required.
- `role_id` (string, required): The role it gives from now on. Required.
- `scope` (Scope, required): Which organizations it covers from now on, as a grant's `scope` says. Required.

## 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/grants>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
