feat: scope client tokens to specific browser origins

[AdirAmsalem]

Summary

Adds an allowed_origins option to client.tokens.create() that scopes a short-lived client token to a specific list of web origins. When the token is later used to open a realtime session, the connection is accepted only if the browser-issued WebSocket Origin header matches one of the listed origins.

This complements allowed_models to give server-side issuers tighter control over how a frontend-bound token can be used. When omitted, no origin restriction is applied.

Usage

from decart import DecartClient

async with DecartClient(api_key=os.getenv("DECART_API_KEY")) as server:
    # Token usable only from https://app.example.com
    token = await server.tokens.create(
        allowed_origins=["https://app.example.com"],
        expires_in=60,
    )

Combine with the existing options:

token = await server.tokens.create(
    allowed_models=["lucy-2.1"],
    allowed_origins=["https://app.example.com"],
    constraints={"realtime": {"maxSessionDuration": 120}},
)

Notes

• Each entry must be a canonical origin (scheme://host[:port]), up to 20 entries.
• Defense-in-depth: enforced via the browser-set Origin header, so it raises the cost of stolen-token abuse from a different web origin but does not protect against attackers controlling a non-browser HTTP client.

Test plan

• uv run pytest tests/test_tokens.py — 10/10 pass, including new allowed_origins request-body test and updated all-options round-trip.
• examples/create_token.py updated to demonstrate the new field.

---

Note

Low Risk
Low risk, additive change that passes a new optional field through to the token-creation API and expands the typed response shape; main risk is mismatched API expectations for the new allowedOrigins/origins fields.

Overview
Adds optional allowed_origins to client.tokens.create() and includes it in the POST body as allowedOrigins, allowing server-issued client tokens to be scoped to specific web origins.

Extends TokenPermissions to optionally include origins, updates the create-token example to display allowed origins, and adds/updates tests to cover request serialization and permissions round-tripping. Also bumps the package version in uv.lock.

^{Reviewed by Cursor Bugbot for commit 7de3f4d. Bugbot is set up for automated code reviews on this repo. Configure here.}