# Access

Every privilege your credential holds in a workspace, and where it holds it.

- `GET /workspaces/{workspace_id}/access` [Read your access in a workspace](#read-access)

## Access object

Every privilege a credential holds in one workspace, each with the organizations where it applies.

- `privileges` (array of AccessPrivilege): Every privilege the caller holds here, with where it holds it.
- `credential` (AccessCredential): The credential the caller presented.

## Read your access in a workspace

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

Preview

Returns every privilege your credential holds in the workspace, and where. For an API token it is the token's own access, inside its scopes and organization limits, never the whole access of the person behind it.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `workspace:read`
- Privilege: `workspace.read`

Needs `workspace.read`. Any grant in the workspace carries `workspace.read`.

### Behavior

- Retry: Safe to send again

### Path parameters

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

### Query parameters

- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `privileges`, `credential`

### Response (200)

- `access` (Access, required): The access.
- `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, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | 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 `workspace.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).

### Example

Read what the token may do

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

Response (200)

```json
{
  "access": {
    "privileges": [
      {
        "id": "organization.read",
        "level": "org",
        "scope": {
          "kind": "selected",
          "org_ids": [
            "0a9e0000-0000-4000-8000-000000000101",
            "0a9e0000-0000-4000-8000-000000000105"
          ],
          "inherited": false,
          "other_orgs": false
        }
      },
      {
        "id": "workspace.read",
        "level": "self",
        "scope": null
      }
    ],
    "credential": {
      "kind": "workspace_key",
      "credential_id": "4b1d0000-0000-4000-8000-000000000804",
      "scope_restriction": "listed",
      "scopes": [
        "workspace:read"
      ]
    }
  },
  "message": "access retrieved"
}
```

## AccessPrivilege object

- `id` (string, required): The privilege's id.
- `level` (one of the values below, required): Where the privilege takes effect: each privilege has one level, the same for every caller, as the role list shows it.
  - `org`: At the organizations it reaches.
  - `workspace`: On the workspace itself.
  - `self`: On the caller's own things.
- `scope` (Scope or null, required): For an org privilege, the organizations it reaches, organizations not token scopes: all, or selected with the topmost organizations it reaches that you can see, each with every organization below it. Null for a workspace or self privilege.

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

## AccessCredential object

- `kind` (one of the values below, required): What kind of credential it is.
  - `session`: A person signed in to the SparkLogs app.
  - `user_key`: A personal token.
  - `oauth`: An OAuth token.
  - `workspace_key`: A workspace token.
- `credential_id` (uuid or null, required): The API token's id, the `credential_id` audit events name; null for a session.
- `scope_restriction` (one of the values below, or null, required): Whether the API token is held to a list of scopes; null for a session.
  - `none`: Every scope its access allows, scopes added later included.
  - `listed`: Only the scopes it lists.
- `scopes` (array of string or null, required): The scopes the API token carries: every scope when `scope_restriction` is none; null for a session.

---

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