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.
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.
- 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.
- 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.
POST /api/agent/v1/session/create/ with a valid X-OTAS-AGENT-KEY. It expires 30 days after issuance.
Header reference
| Header | Type | When to use |
|---|---|---|
X-OTAS-USER-TOKEN | User JWT | All management API calls: create project, create agent, list resources, manage keys |
X-OTAS-PROJECT-ID | Project UUID string | Sent alongside X-OTAS-USER-TOKEN to scope the request to a specific project |
X-OTAS-SDK-KEY | Backend SDK key | Server-side middleware logging events on behalf of agents |
X-OTAS-AGENT-KEY | Agent key | Agent authenticating to create sessions or log events directly |
X-OTAS-AGENT-SESSION-TOKEN | Session JWT | Logging events scoped to a specific agent session |
X-OTAS-AGENT-ID | Agent UUID string | Sent alongside X-OTAS-USER-TOKEN and X-OTAS-PROJECT-ID for user-agent authentication checks |
Security notes
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
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.Deploy the new key
Update your environment variables or secrets manager with the new key value before the old one expires.
Verify traffic
Confirm events are still flowing in the OTAS dashboard before decommissioning the old key configuration.