Embed token

POST /sveda/embed/token

Enable with SVEDA_EMBED_ENABLED=true or the route returns 404. Request body EmbedTokenRequest: visitor_id, host_mcp_url, host_mcp_token — all optional in isolation. Empty visitor_id becomes a UUID (max 64 chars). Response EmbedTokenResponse: token, visitor_id, expires_in (seconds; default TTL 3600 via SVEDA_EMBED_TOKEN_TTL, minimum 60). Token prefix sveda_embed_.

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

{
  "visitor_id": "visitor-123",
  "host_mcp_url": "https://app.example.com/mcp",
  "host_mcp_token": "host-mcp-secret"
}

{
  "token": "sveda_embed_…",
  "visitor_id": "visitor-123",
  "expires_in": 3600
}

const res = await fetch('http://127.0.0.1:8787/sveda/embed/token', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-sveda-host-key': process.env.SVEDA_EMBED_HOST_API_KEY ?? '',
  },
  body: JSON.stringify({
    visitor_id: 'visitor-123',
  }),
})
const { token, visitor_id, expires_in } = await res.json()

Visitor header

Stream, message, histories, and document extract authenticate the visitor with the embed token. Prefer x-sveda-embed-token. Authorization: Bearer sveda_embed_… is accepted when the value starts with sveda_embed_.

x-sveda-embed-token: sveda_embed_…

Authorization: Bearer sveda_embed_…

Host key

If SVEDA_EMBED_HOST_API_KEY is unset, minting does not require a host key. If it is set, send x-sveda-host-key or Authorization: Bearer with a value that is not a sveda_embed_ token. Missing or mismatched key returns 401.

URL + token pairing

host_mcp_url and host_mcp_token must be paired. One without the other is 422. The URL must be http:// or https:// only. Stored MCP creds are keyed by visitor_id and only persist when a host API key is configured. Call flow: MCP and tools. Product: embed tokens.

Mint from a host SDK

Do not call this route from the browser. Language SDKs wrap POST /sveda/embed/token and expose POST /sveda/session to the page. Numbered install:

1. No framework — curl, iframe, or a tiny HTTP handler.
2. PHP and Laravel
3. Python — Flask, Django, FastAPI
4. Node — Express, NestJS, Next.js
5. Ruby, Go, Java, .NET