Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pewdiepie-archdaemon/odysseus/llms.txt

Use this file to discover all available pages before exploring further.

API tokens let external scripts, automation pipelines, and integrations call Odysseus endpoints without an interactive login session. Instead of a browser cookie, the caller presents a bearer token in the Authorization header. Tokens are created, named, scoped, and revoked from the admin panel — no .env changes required. This is an admin-only feature: only accounts with the admin role can create or manage tokens.

​
Creating a Token

  1. Go to Settings → API Tokens.
  2. Click Create Token.
  3. Give the token a descriptive name (e.g. automation-scripts, mobile-companion, ci-pipeline).
  4. Optionally select a profile or individual scopes (see below).
  5. Click Create and immediately copy the token value shown.
The full token value is shown only once at creation time. It is stored as a bcrypt hash — Odysseus cannot recover or display it again. If you lose the token, delete it and create a new one.
Token values always begin with the ody_ prefix, for example: 
ody_Ax7kLmN9qRsTuVwXyZ0aBcDeFgHiJkLmNoPqRsT

​
Using a Token

Pass the token as a bearer credential in the Authorization header on any API request: 
curl -H 'Authorization: Bearer <your-token>' http://localhost:7000/api/sessions
Tokens authenticate over the same routes as browser sessions. An authenticated API request can access any endpoint that the token’s scopes permit.

​
Token Scopes

Every token is issued with one or more scopes that limit which endpoints the token can reach. You can choose a named profile (a predefined scope bundle) or select scopes individually. Available profiles:
ProfileScopes granted
chatchat
codex_todostodos:read, todos:write
codex_email_draftsemail:read, email:draft, documents:read, documents:write
All available individual scopes:
ScopeAccess granted
chatStart and continue chat/agent sessions
todos:readRead tasks and to-do items
todos:writeCreate and update tasks
documents:readRead documents
documents:writeCreate and edit documents
email:readRead email messages
email:draftCreate email draft replies
email:sendSend email
calendar:readRead calendar events
calendar:writeCreate and update calendar events
memory:readRead persistent memories
memory:writeAdd and update memories
Write scopes automatically include their corresponding read scope. For example, granting todos:write always includes todos:read, even if you did not select it explicitly.

​
One Token Per Integration

Create a separate token for each integration or script. This makes it easy to revoke access for a single consumer without affecting others, and gives you a clear audit trail of which token is used where. 
automation-scripts  →  ody_Ax7kLmN9...
mobile-companion    →  ody_Bq3rJpK8...
ci-pipeline         →  ody_Cz9mNwL4...

​
Revoking a Token

Go to Settings → API Tokens, find the token by name or its visible prefix, and click Delete. Revocation is immediate — the token stops authenticating on the next request that uses it. When an admin account is deleted, all API tokens owned by that user are automatically revoked.

​
Webhook Tokens

Webhooks use a separate token mechanism managed at Settings → Webhooks. Webhook tokens are not the same as API tokens and are not listed or managed from the API Tokens page.
Treat API tokens like passwords. Do not commit them to source control, paste them into shared chats, include them in screenshots, or store them in unencrypted notes. If a token is ever exposed, delete it immediately and create a replacement.

Build docs developers (and LLMs) love

Get started for freeTalk to us