Authentication
Osyra has two public security planes with different jobs:
https://auth.osyra.aiis the authorization server. It owns OAuth, login, token issuance, discovery, and token-signing keys.https://api.osyra.aiis the protected API ingress. It validates credentials and the canonical API audience before any control-plane or model operation runs.
Most API routes require exactly one of these credentials:
Authorization: Bearer <OAuth access token>X-Api-Key: osy_live_<secret>Do not send both headers. Edge rejects ambiguous credentials instead of choosing one. Public exceptions are intentionally narrow: health, OAuth discovery and token routes, and pre-auth account flows such as signup and password recovery.
OAuth access tokens
Use an access token issued by auth.osyra.ai for interactive sessions, automation that already uses OAuth, and control-plane GraphQL. Edge verifies the signature, issuer, audience, token type, expiry, revocation state, tenant claims, and operation permissions before dispatch.
The token's audience identifies the protected API (api.osyra.ai); it does not turn the authorization server into the API ingress. See why the two hosts are separate below.
API keys
API keys are workspace-bound machine credentials. Send the plaintext in X-Api-Key; Edge exchanges it with IAM for a short-lived, workspace-bound API-key session and removes the plaintext before forwarding the request. Unknown, expired, and revoked keys fail with the same opaque authentication response.
The console is the recommended place to create, rotate, and revoke keys. Those controls call authenticated GraphQL operations; they are not anonymous minting endpoints. New plaintext is returned once and cannot be read back later.
| Prefix | Lifecycle contract |
| -------------- | --------------------------------------------------------------------------------- |
| osy_sandbox_ | One active key per user, 24-hour default lifetime, and a constrained daily quota. |
| osy_test_ | Test-class key; no default expiry unless one is requested. |
| osy_live_ | Live-class key; no default expiry unless one is requested. |
Key class is not a promise of fake or canned inference. In strict BYOK mode, the broker does not fabricate a response or use an ambient credential when workspace credential resolution fails; it returns the typed no-provider-connected error.
Authorization
Permissions are carried in the verified session and evaluated server-side at protected operation boundaries. For example, model calls require the projected osyra:llm:model:invoke permission, while workspace-wide API-key administration requires osyra:iam:api_keys:manage. Wildcards follow the Osyra Security Policy grammar; look-alike strings do not grant access.
Choose the smallest role and permission set that supports the workload. A key remains bound to its owner, organization, and workspace; request bodies and headers cannot move it into another tenant.
Rotation and revocation
Rotation atomically revokes the old key and returns a replacement plaintext once. Update the consuming secret store immediately and keep the replacement out of logs, URLs, analytics, and browser storage.
Revocation is enforced when IAM authenticates the plaintext key. The public error is intentionally uniform, so callers cannot use it to distinguish an unknown key from a known-but-revoked one. Treat any authentication rejection as terminal for that credential and rotate through an authorized operator.
Bring-your-own provider credentials
Configure provider credentials in Virtual keys. Osyra stores credential material server-side and exposes metadata and lifecycle controls to the browser, not the secret after creation. In strict BYOK mode, the broker resolves a credential for the verified workspace and fails closed when none is available.
Osyra does not substitute canned responses when a resolvable workspace provider credential is missing. In strict BYOK mode, the request fails with the typed no-provider-connected error.
Workspace boundary
API keys and access-token sessions are bound to organization and workspace claims issued by IAM. Edge derives tenant context from those verified claims and rejects conflicting workspace selectors. Cross-workspace administration uses an authorized user session with the required workspace permission; there is no osy_admin_ key class.
Security boundaries
Keeping auth.osyra.ai and api.osyra.ai separate limits credential exposure and gives each host a single security role. The authorization server issues tokens for the API audience; the API ingress consumes those tokens. OAuth discovery lives under auth.osyra.ai/.well-known/, while model and control-plane traffic goes only to api.osyra.ai.
What's next
- Making requests — chat, embeddings, streaming
- Errors — selected shared authentication codes
- Governance & policy — attach policies to keys