Authentication

Dispatched uses a cryptographic session handshake. Your private key never leaves your device.

Browser sign-in

Go to /login and enter your tenant ID, API key, and private key. The browser performs the handshake automatically using the Web Crypto API — your private key stays in browser memory and is never transmitted.

Sessions last 1 hour by default. You stay signed in across page refreshes and server restarts.

How it works

When you sign in, a Diffie-Hellman key exchange establishes a secure session:

  1. Your browser generates a temporary keypair
  2. The server generates its own temporary keypair
  3. Both sides derive a shared session key
  4. Your browser derives a wrapping key from your private key
  5. The wrapping key is sent to the server, encrypted with the session key
  6. The server caches the wrapping key for the session duration

The wrapping key encrypts and decrypts your data. It’s derived from your private key via a one-way function — even if the wrapping key were exposed, your private key cannot be recovered from it.

CLI tool

The dispatched CLI handles authentication for API access. Download it or build from source (cli/ directory in the repo).

One-time setup:

dispatched init
# Host URL [http://localhost:4000]: https://dispatched.work
# Tenant ID: ten_abc123
# API Key: dsk_live_xxx
# Private Key (base64): <paste your key>

Credentials are saved to ~/.config/dispatched/credentials.json.

Authenticate:

dispatched login
# Authenticating as ten_abc123 at https://dispatched.work...
# Authenticated. Session expires in 60m.

Use with curl or httpie:

curl https://dispatched.work/api/workflows/my-workflow \
  -H "Dispatched-Session: $(dispatched token)"

Check status:

dispatched status
# Host:      https://dispatched.work
# Tenant:    ten_abc123
# Session:   active (58m remaining)

The CLI performs the full DH handshake — your private key never leaves your machine.

API access without the CLI

If you can’t use the CLI, implement the DH handshake in your client. See the API Reference for session endpoints:

  1. POST /api/session — initiate handshake with your ephemeral public key
  2. POST /api/session/confirm — complete handshake, receive session token

Then include the token in all requests:

Dispatched-Session: dst_sess_...

Multiple tenants

You can sign in as multiple tenants simultaneously. Use the tenant switcher in the sidebar to switch between them or add another.

Session lifecycle

  • Sessions expire after 1 hour
  • Extend with POST /api/session/refresh
  • Sign out removes only the active tenant’s session
  • Signing out with multiple tenants switches to the next one