Skip to content

API Keys

API keys give scripts, automation, and tools like eosctl and the MCP server persistent authentication to your Eight.ly OS box. Unlike a session cookie, a key doesn't expire until you revoke it.

Signing out of the dashboard breaks that account's API keys too

A key isn't fully independent of the dashboard session: logging the owning account out, changing its password, or changing its role invalidates every API key that account has created, not just its browser session. If a script or an assistant using a key suddenly starts getting rejected, check whether someone logged that account out or changed its password before assuming the key was revoked or corrupted.

Creating an API key

  1. Navigate to Settings > Security > API Keys
  2. Click Create Key
  3. Enter a label (for example, "backup script" or "laptop assistant")
  4. Copy the key immediately — it's only shown once

Copy it now

The full key is displayed only at creation. Eight.ly stores a SHA-256 hash of it, not the key itself — if you lose it, revoke it and create a new one.

Key format

Keys look like eos_ followed by 64 hex characters:

eos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The list screen shows only the label and the first 12 characters (eos_ plus 8 hex digits) — the full key is never re-displayed after creation.

What a key can do

A key has no scope of its own. It's tied to the account that created it, and it can do exactly what that account's role allows — admin, operator, or viewer (see API Reference). There is currently no way to narrow a key beyond that: create it from a less-privileged account if you want to hand a script or an AI assistant less than full access. This matters most for the MCP server, where the key you give it determines everything the assistant on the other end is allowed to do.

Using an API key

curl -H "Authorization: Bearer eos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  http://box.example.lan:8080/api/health

curl -H "Authorization: Bearer eos_..." http://box.example.lan:8080/api/containers
curl -H "Authorization: Bearer eos_..." http://box.example.lan:8080/api/system

With eosctl:

export EOS_BEARER_AUTH="eos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
eosctl doctor

See eosctl for the full command line tool, and the MCP server for connecting an AI assistant.

Revoking a key

  1. Go to Settings > Security > API Keys
  2. Find the key by its label
  3. Click the revoke button
  4. Confirm

Revocation is immediate and cannot be undone. Any script or tool using that key gets rejected on its next request.

Security

  • Keys are hashed (SHA-256) at rest — a database breach doesn't expose raw keys
  • Each key has a unique label for tracking which tool or script owns it
  • A key inherits the account's role at the moment it's used, and is invalidated the next time that account's session generation changes — logout, password change, or role change all bump it, so a leaked key doesn't outlive the account action that would also kill a session
  • Revoked keys cannot be reactivated — create a new one instead
  • Use a separate key per script or tool so you can revoke one without breaking the others