Skip to main content
Every request to OTAS is authenticated. Which credential you use depends on who is making the request: a human user managing the platform, a server-side middleware layer logging events, or an AI agent acting autonomously. Understanding which credential belongs where prevents authentication errors and keeps your keys appropriately scoped.

​
Credential types

​
User JWT (X-OTAS-USER-TOKEN)

A user JWT is issued when a user logs in. It identifies a specific user account and is required for all management operations: creating projects, creating agents, listing resources, and managing keys.
User tokens are short-lived. When you make requests to project-scoped endpoints, send this token alongside X-OTAS-PROJECT-ID so OTAS can verify your membership and privilege level for that project.

​
Backend SDK key (X-OTAS-SDK-KEY)

A Backend SDK key is a project-scoped secret your server-side middleware uses to log events without a user session. It is suitable for always-on processes such as API proxies or interceptors that run in production.
Key properties:
  • Format: otas_<prefix>_<secret>
  • Scoped to one project; the project is resolved automatically from the key
  • Configurable expiry between 1 and 300 days
  • Hashed in the database; the plain-text value is shown only at creation
  • Can be revoked immediately via the API

​
Agent key (X-OTAS-AGENT-KEY)

An Agent key is issued to a specific agent and is used by that agent—or the code that runs it—to authenticate session creation and direct event logging.
Key properties:
  • Format: agent_<prefix>_<secret>
  • Scoped to one agent; the agent and its project are resolved from the key
  • Expires 30 days after creation
  • Rotating a key revokes all existing active keys for that agent and issues a new one
  • Hashed in the database; plain-text value shown only at creation

​
Agent session JWT (X-OTAS-AGENT-SESSION-TOKEN)

After an agent creates a session, OTAS returns a short-lived JWT that encodes the agent_session_id and agent_id. Pass this token when logging events to associate them with the current task or run.
The session JWT is obtained by calling POST /api/agent/v1/session/create/ with a valid X-OTAS-AGENT-KEY. It expires 30 days after issuance.

​
Header reference

​
Security notes

Both BackendAPIKey and AgentKey values are hashed in the database using Django’s password hashing framework. OTAS never stores plain-text keys. If you lose a key, you must rotate it—there is no recovery option.
Agent keys expire after 30 days. Rotating a key before it expires is the recommended approach; revoke the old key explicitly only if it is compromised before its expiry.

​
Rotation workflow

1

Generate a new key

Call the key creation endpoint (POST /api/project/v1/sdk/backend/key/create/ for SDK keys, or POST /api/agent/v1/agents/key/create/ for agent keys). For agent keys, the previous active key is revoked automatically.
2

Deploy the new key

Update your environment variables or secrets manager with the new key value before the old one expires.
3

Verify traffic

Confirm events are still flowing in the OTAS dashboard before decommissioning the old key configuration.
4

Revoke if compromised

If a key is exposed before its expiry, revoke it immediately via the revoke endpoint. Revocation takes effect on the next request.