# Credential

The credential that authenticates a call: read what it is and which workspace it belongs to, or give a token a new secret.

A workspace token reads its credential to learn its workspace id, which every other path needs.

Belongs to: [Workspaces](https://sparklogs.com/docs/api/reference/workspaces.md), [Regions](https://sparklogs.com/docs/api/reference/regions.md)

Contains: [Audit events](https://sparklogs.com/docs/api/reference/audit-events.md)

Ids: uuid.

- `GET /credential` [Read credential metadata](#read-credential)
- `POST /credential/rotate` [Rotate the credential's secret](#rotate-credential)

## Credential object

The credential that authenticated a call: a signed-in session or an API token, with the workspace a token belongs to, its scopes and when it expires.

- `kind` (one of the values below): 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): The API token's id, the `credential_id` audit events name; null for a session.
- `workspace_id` (uuid or null): The one workspace the API token belongs to; null for a session.
- `region_id` (string or null): The id of the region that workspace's data lives in; null for a session.
- `scope_restriction` (one of the values below, or null): 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): The scopes the API token carries: every scope when `scope_restriction` is none; null for a session.
- `expires_at` (date-time or null): When the API token stops working; null when it never expires, and for a session.

## Read credential metadata

`GET https://engine.sparklogs.app/app-api/credential`

Preview

Returns what the credential on this request is: a session, or an API token with its id, the one workspace it belongs to, that workspace's region, its scopes and when it expires. A workspace token calls it to learn its workspace id.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token

Needs no privilege: it reads only the credential that authenticates the call.

### Behavior

- Retry: Safe to send again

### Query parameters

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

Sent by default: `kind`, `credential_id`, `workspace_id`, `region_id`, `scope_restriction`, `scopes`, `expires_at`

### Response (200)

- `credential` (Credential, required): The credential.
- `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 |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | 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

- [Rotate the credential's secret](https://sparklogs.com/docs/api/reference/credential.md#rotate-credential)
- [Read a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#read-workspace)
- [Read your access in a workspace](https://sparklogs.com/docs/api/reference/access.md#read-access)

### Example

Learn the workspace a deployment token belongs to

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/credential" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "credential": {
    "kind": "workspace_key",
    "credential_id": "4b1d0000-0000-4000-8000-000000000803",
    "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
    "region_id": "us-central",
    "scope_restriction": "listed",
    "scopes": [
      "workspace:read",
      "fleet:deploy"
    ],
    "expires_at": "2027-11-10T09:00:00Z"
  },
  "message": "credential retrieved"
}
```

## Rotate the credential's secret

`POST https://engine.sparklogs.app/app-api/credential/rotate`

Preview · Returns a secret · Destructive

Gives the personal token or workspace token that authenticates this call a new secret and returns it, once. The old secret stops working at once on this API, and `cache_clear_status` says whether every other SparkLogs service refuses it. The token's id, label, scopes, grants and expiry stay. When the token was revoked, deleted or rotated while the call ran, nothing changes and the call returns 409. The rotation is recorded in the audit log. 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: Personal token, Workspace token

Needs no privilege: the token that authenticates the call acts on itself and nothing else.

### Behavior

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

### Response (200)

- `credential_id` (uuid, required): The API token's id, which rotation does not change.
- `token` (string, required): The new secret. It is sent only this once and cannot be read again. The old secret is refused in every region `cache_clear_status` says the change reached.
- `workspace_id` (uuid, required): The workspace the API token belongs to.
- `user_id` (string or null, required): The person a personal token acts as; null for a workspace token.
- `label` (string or null, required): The API token's label.
- `scope_restriction` (one of the values below, required): Whether the API token is held to a list of scopes.
  - `none`: Every scope its access allows, scopes added later included.
  - `listed`: Only the scopes it lists.
- `scopes` (array of string, required): The scopes the API token carries: every scope when `scope_restriction` is none.
- `expires_at` (date-time or null, required): When the API token stops working, which rotation does not change; null when it does not expire.
- `cache_clear_by_region` (map of string or null, required): For each region whose cache may still hold the old secret, whether that cache dropped it: ok, failed or disabled. Null when there was nothing to drop.
- `cache_clear_status` (one of the values below, required): Whether every region refuses the old secret.
  - `ok`: Every region refuses the old secret.
  - `failed`: A region could not be reached. The old secret can keep working there until its cache expires.
  - `disabled`: This environment does not clear regional caches. The old secret can keep working until each region's 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` | 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_CREDENTIAL_NOT_ADMITTED` | The call does not take a credential of this kind: `session`, `oauth`. | No |
| 409 | `APP_API_ERR_CONFLICT` | The token was revoked, deleted or expired, or rotated by another call while this one ran. | 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 `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

- [Read credential metadata](https://sparklogs.com/docs/api/reference/credential.md#read-credential)

### Example

Give the presented deployment token a new secret

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/credential/rotate" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

Headers: `Cache-Control: no-store`

```json
{
  "message": "token rotated",
  "credential_id": "4b1d0000-0000-4000-8000-000000000803",
  "token": "sl_us_EXAMPLE_NOT_A_REAL_TOKEN",
  "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
  "user_id": null,
  "label": "RMM deployment",
  "scope_restriction": "listed",
  "scopes": [
    "workspace:read",
    "fleet:deploy"
  ],
  "expires_at": "2027-11-10T09:00:00Z",
  "cache_clear_by_region": {
    "us-central": "ok"
  },
  "cache_clear_status": "ok"
}
```

---

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