# Auth and scopes

Owners/admins create API credentials from the app or an authenticated web session.

## Create a key

```text
POST /api/v1/credentials
Cookie: sb-*-auth-token=...
Content-Type: application/json

{
  "workspaceId": "00000000-0000-0000-0000-000000000000",
  "name": "Production integration",
  "workspaceRole": "member",
  "scopes": ["agents:read", "models:read", "projects:read", "conversations:read", "conversations:write"]
}
```

The plaintext secret is returned once. Store it immediately.

## Public endpoints

```bash
curl https://saas.ha.knwl.me/api/v1/agents -H "Authorization: Bearer $LOQY_API_KEY"
```

- `GET /api/v1/capabilities`: `settings:read`.
- `GET /api/v1/agents`: `agents:read`; ids for agent-mode conversations.
- `GET /api/v1/models`: `models:read`; runtime model ids/default.
- `GET /api/v1/projects`: `projects:read`.
- `GET /api/v1/conversations`: `conversations:read`.
- `POST /api/v1/conversations`: `conversations:write` + `Idempotency-Key`.

Messages, documents, artifacts, runs, and webhooks are not public v1 contracts yet.

## Limits

- Public routes: `120/min/IP` plus monthly workspace quota.
- Credential creation: `30/min/user`, session-authenticated.
- Add `x-request-id` for traceable smoke calls.
- `429` includes `Retry-After`; successful responses are `no-store`.