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.

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:

Which endpoint needs what

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. The response says what is required and what the key has:

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

{
  "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, never 403, so the API never reveals whether such a resource exists.