Authentication

Programmatic access uses a two-step flow: exchange your org API key for a short-lived JWT, then call the agent API with that JWT.

The Free plan does not include API keys; they are on Pro and up.

Step 1 — Create an API key

Owners and admins create keys.

Go to Console → Settings → Security
Under API keys, click New key
Enter a name, choose the Agent role and an expiry, then click Create key
Copy the key. You won’t see it again

Org API keys start with sk_live_ and look like: sk_live_abc123xyz789...

Step 2 — Exchange for a JWT

POST https://profile-api.auteryn.ai/api/v1/auth/exchange/agent-token
X-API-Key: sk_live_your_key
Content-Type: application/json

{
  "agent_id": "your-agent-uuid"
}

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "org_id": "your-org-uuid",
  "agent_id": "your-agent-uuid"
}

The JWT expires in 1 hour. Exchange again when it expires. A key with a role other than Agent gets 403 here. See Token lifetime for what that means for a long run.

For member-scoped access (acting as a specific person in your organization), use POST /api/v1/auth/exchange/member-token instead, with a Member key and that person’s user ID as user_id. See Member tokens.

Step 3 — Call the agent API

Authorization: Bearer eyJ...
X-Agent-Id: your-agent-uuid
Content-Type: application/json

Agent API base URL: https://agent-api.auteryn.ai

curl -X POST https://agent-api.auteryn.ai/api/run \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Agent-Id: agent_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Summarize the open GitHub issues"}],
    "stream": false
  }'

To copy your agent’s ID, open the agent in the Console and choose More actions (⋯) → Copy agent ID.

Agent token scope

An agent token runs the one agent you named at exchange. It can call seven endpoints, and only for conversations that an agent token of that agent started:

Endpoint	Use
`POST /api/run`	Start a run, or continue one of its own conversations
`POST /api/run/async`	Start a background run
`GET /api/run/{task_id}/status`	Check whether a run is active and how far it has got
`GET /api/run/{task_id}/reconnect`	Rejoin a run’s stream, or fetch its final state
`GET /api/tasks/{task_id}/stream`	Follow a conversation’s events (SSE)
`GET /api/runs/{run_id}/events`	Read a run’s events as JSON
`POST /api/tasks/{task_id}/cancel`	Stop the active run

Every other endpoint answers 403 with An agent token can only start, follow and stop runs of its own agent. That includes listing tasks and reading messages or memories.

Agent. X-Agent-Id must be the agent the token was exchanged for, in any UUID spelling. Another agent answers 403 (This token was issued for a different agent.).
Conversations. The token reaches only conversations that an agent token of its agent started, never your team’s own. For any other conversation, POST /api/run, POST /api/run/async, stream and cancel answer 403, and status, reconnect and run events answer 404.
Task IDs. Give each new task_id on /api/run/async a fresh UUID. An ID that another organization already holds answers 409 (That task_id is unavailable.) to every caller.
Customers and Loops. An agent token cannot start a run for a customer or a Loop (403). Replying to a customer on a Channel is a Loop’s job.
Your own machine. An agent that works on one of your team’s own machines cannot be run with an agent token.

Waiting for a person

An agent can stop to ask a question or for an approval. You cannot answer with an agent token: POST /api/tasks/{task_id}/input and the approval endpoints answer 403. The run waits for a member of your organization to answer in the workspace, where members are notified. Unanswered after 72 hours, an approval counts as rejected and a question expires. Your organization can set a shorter question timeout for questions.

To answer from your own code, use a member token.

Token lifetime

A run uses the token it started with for its computer. When that token expires, a run that is still going, or still queued, loses its computer. Exchange for a fresh token right before each run, and keep runs you start through the API short: a Deep run can last up to about two hours. Auteryn does not refresh the token of a run that has started.

Conversations in the workspace

A conversation started through the API appears in the workspace, where your team’s members can read it.

Member tokens

A member token acts as the person you name, with that person’s access to the agent. It can call what an agent token cannot, including the task list, messages, memories, Knowledge retrieval and approvals. It lasts 1 hour too.

Create a key with the Member role the same way as an Agent key, then exchange it:

POST https://profile-api.auteryn.ai/api/v1/auth/exchange/member-token
X-API-Key: sk_live_your_member_key
Content-Type: application/json

{
  "user_id": "the-person-uuid"
}

user_id must be the ID of an active person in your organization. A Member key cannot be exchanged for an agent token, and an Agent key cannot be exchanged for a member token (403).

Browser sessions

When using the Console or Workspace in a browser, authentication uses the auth_session cookie (JWT issued at login). You do not need an API key for in-app chat.

Security

API keys are org-scoped
Always use HTTPS — never send keys over plain HTTP
Store keys in environment variables, not in source code
Revoke a key you think leaked: Settings → Security → API keys → Revoke

Error responses

Status	Meaning
`401`	Missing, invalid, expired or revoked API key or JWT
`403`	Token valid but no access to this resource, or the key’s role does not match the exchange
`409`	A `task_id` that another organization already holds
`429`	Too many requests — slow down

An agent token that calls an endpoint outside its seven also gets 403.