> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devias.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The docs are served at https://docs.devias.io. Every path in these docs is relative to that root: /llms.txt is https://docs.devias.io/llms.txt.
> Devias is an open-source platform that works as an operating system for a business: a core (records, views, workflows, agents, permissions) with installable modules.
> Pages are typed by folder. concepts/ explains what things are, guides/ gives procedures, reference/ is exhaustive (SDK, CLI, HTTP API), operate/ covers hosting. Use /start/glossary for exact terms.
> Every id in a module (module, object, field, view, action, workflow, step, connection, variable, event, policy) is a uuid. Generate them with `devias id <count>`. Never invent dotted or readable ids.
> Run `devias plan` and read its output before `devias apply`. Apply only what the plan says.
> The OpenAPI document, including the routes of the modules in the reference setup, is at /reference/api/openapi.json.
> Devias is young and changes quickly. If a page and the source repository (github.com/devias-io/devias) disagree, the repository is right.

# API authentication

> How to authenticate to the Devias HTTP API. The studio uses a session cookie. Scripts, servers and the CLI use an API key sent in the x-api-key header. A key belongs to one workspace, carries a permissions map, and a call outside it is refused with FORBIDDEN.

A request authenticates in one of two ways: a session cookie or an API key.

## Session cookie, for the studio

People sign in through the studio, and the server sets a session cookie. A browser app that calls the API sends that cookie with each request. The studio itself works this way.

## API key, for scripts, servers and the CLI

An **API key** is created in **Settings → API keys** with an expiry. It is shown once, when it is created. It is sent in the `x-api-key` header.

```bash theme={"dark"}
curl -X POST "https://api.example.com/api/workspaces/<workspaceId>/records/person/list" \
  -H "x-api-key: $DEVIAS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "limit": 5 }'
```

A successful call returns `{ "items": [...], "nextCursor": ... }`. The route `GET /api/me` requires a signed-in person and does not accept an API key.

A key belongs to one workspace and only works there.

## Permissions of a key

Each key carries a map from an area to the actions it allows. A call outside that map is refused with `FORBIDDEN`.

```json theme={"dark"}
{ "record": ["read", "write"] }
```

A key made in the studio can read records. A key with more permissions is created through the API with a `permissions` map. For example, `devias plan` and `devias apply` need `{ "module": ["manage"] }`. A key should have only what it needs and should be deleted when no longer used.

## Related

* [Errors](https://docs.devias.io/reference/api/errors.md): what `FORBIDDEN` and `UNAUTHORIZED` look like.
* [Access and permissions](https://docs.devias.io/concepts/access.md): roles, keys, workflows and agents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.