# Scopes

> The three scopes you choose when you create a key and what each one opens.

Source: https://diko.app/en/api-docs/scopes

## Scope table

Scopes decide which endpoints a key can call. You choose them when you create a key, and they cannot be changed afterwards: you need a new key.

| Scope | Allows | Events |
|---|---|---|
| `meetings:read` | every `GET /meetings*` endpoint | `meeting.*` |
| `library:read` | `GET /library/transcripts*` and `GET /library/imports*` | `library.*` |
| `library:write` | `POST /library/imports` and `POST /library/imports/{import_id}/cancel`. **Includes `library:read`** | `library.*` |

`GET /` and `GET /me` work with any valid key. `GET /me` always masks the account e-mail and returns the credit balance only to a key with `library:write`. In the app the scopes are called **Susitikimai – skaityti** (Meetings – read), **Biblioteka – skaityti** (Library – read) and **Biblioteka – importuoti** (Library – import).

## Templates

When you create a key you can pick a template or tick the scopes yourself:

| Template | Scopes |
|---|---|
| **Tik skaitymas** (Read only) | `meetings:read`, `library:read` |
| **Skaitymas ir importas** (Read and import) | `meetings:read`, `library:write` |

## Which endpoint needs what

| Endpoint | Scope |
|---|---|
| [`GET /`](https://diko.app/en/api-docs/reference/get-api-index.md) | no key needed |
| [`GET /me`](https://diko.app/en/api-docs/reference/get-me.md) | any valid key (`credits` only with `library:write`) |
| [`GET /meetings`](https://diko.app/en/api-docs/reference/list-meetings.md), [`/meetings/{meeting_id}`](https://diko.app/en/api-docs/reference/get-meeting.md), [`/transcript`](https://diko.app/en/api-docs/reference/get-meeting-transcript.md), [`/minutes`](https://diko.app/en/api-docs/reference/get-meeting-minutes.md), [`/action-items`](https://diko.app/en/api-docs/reference/list-meeting-action-items.md) | `meetings:read` |
| [`GET /library/transcripts`](https://diko.app/en/api-docs/reference/list-library-transcripts.md), [`/library/transcripts/{transcript_id}`](https://diko.app/en/api-docs/reference/get-library-transcript.md), [`/transcript`](https://diko.app/en/api-docs/reference/get-library-transcript-transcript.md) | `library:read` |
| [`GET /library/imports`](https://diko.app/en/api-docs/reference/list-library-imports.md), [`/library/imports/{import_id}`](https://diko.app/en/api-docs/reference/get-library-import.md) | `library:read` |
| [`POST /library/imports`](https://diko.app/en/api-docs/reference/create-library-import.md), [`POST /library/imports/{import_id}/cancel`](https://diko.app/en/api-docs/reference/cancel-library-import.md) | `library:write` |
| [`GET /events`](https://diko.app/en/api-docs/reference/list-events.md), [`GET /events/{event_id}`](https://diko.app/en/api-docs/reference/get-event.md) | any key; results are filtered by scope |

## How to choose

- **Grant the smallest scope that works.** A reporting or CRM sync integration needs only **Tik skaitymas** (Read only).
- **Imports need `library:write`.** It already includes reading the library, so an importer can check the import status and read the result itself.
- **One key per integration.** That makes it easy to revoke only the key whose secret leaked and to see which system uses what.

## A missing scope

If a key lacks the scope an endpoint needs, the API returns 403 [`insufficient_scope`](https://diko.app/en/api-docs/errors.md#insufficient_scope). The response says what is required and what the key has:

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="diko", error="insufficient_scope", scope="meetings:read"
```

```json
{
  "type": "error",
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "The API key lacks the permission this endpoint needs.",
    "doc_url": "https://diko.app/en/api-docs/errors#insufficient_scope",
    "details": {
      "required_scopes": ["meetings:read"],
      "granted_scopes": ["library:read"]
    }
  },
  "request_id": "req_QBPIQ5QTIWAUYTMDNCLD7CMKBE"
}
```

The fix: create a new key with the scope you need and update your system. Revoke the old key if you no longer need it.

## Scopes and the event stream

`GET /events` shows only events of the families the key can read: `meeting.*` with `meetings:read`, `library.*` with `library:read` or `library:write`. If the key can read no family, the list is empty rather than 403.

## Other accounts' resources

A key sees only its owner's data. Another account's, a non-existent or a wrongly encoded ID always returns 404 [`not_found`](https://diko.app/en/api-docs/errors.md#not_found), never 403, so the API never reveals whether such a resource exists.