# auth.md

Sveda is a self-hosted embeddable agent. **https://sveda.dev is the product site and documentation.** It does not create agent accounts or mint live credentials.

## Audience

Host backends, install agents (Cursor, Claude Code, and similar), and operators running `sveda-server` beside their app.

## Provisioning

Credentials live on the operator's runtime, default bind `0.0.0.0:8787`. Enable minting with `SVEDA_EMBED_ENABLED=true`.

1. Set `SVEDA_EMBED_HOST_API_KEY` on the runtime.
2. From the host server, `POST /sveda/embed/token` with that host key.
3. Return `{ origin, token, expires_in }` to the browser. The browser never holds the host key.

Registration URI (documentation, not an account-create POST): https://sveda.dev/docs/embed

## Methods

| Method | Where | How |
| --- | --- | --- |
| Host API key | Operator runtime | Header `x-sveda-host-key` (or Bearer) on `POST /sveda/embed/token` |
| Embed token | Browser / JS client | Header `x-sveda-embed-token` or `Authorization: Bearer sveda_embed_…` on stream and JSON turns |
| Admin key | Operator runtime | Header `x-sveda-admin-key` for admin settings |

Tokens are HMAC, prefixed `sveda_embed_`, scoped to `visitor_id`. Default TTL is 3600 seconds.

## Credential use

```
POST {runtime}/sveda/embed/token
Content-Type: application/json
x-sveda-host-key: $SVEDA_EMBED_HOST_API_KEY

{"visitor_id":"visitor-123"}
```

The JS client then calls `session.send` against `{runtime}/sveda/stream` with `x-sveda-embed-token`.

This origin does not speak OAuth authorization-code login. Discovery documents at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` exist so agents can find this page and the OpenAPI spec. Token minting stays on the self-hosted runtime.

## Install with an agent

Read https://sveda.dev/llms.txt and https://sveda.dev/docs/start. Skill: https://sveda.dev/.well-known/agent-skills/sveda-install/SKILL.md