SpiderMail

Authentication

To use SpiderMail outside the dashboard — from the CLI, an MCP agent, or the API directly — you need a token. This page covers how to get one and how authentication works.

Getting access

The simplest path is the request-and-approve flow from the CLI:

spideriq auth request --email you@yourcompany.com

This sends an approval request to your workspace admin. Once approved, your credentials are issued and stored locally, and the CLI and MCP server reuse them automatically. Check your status any time:

spideriq auth whoami

Token format

API requests authenticate with a bearer token made of three parts — your client id, an API key, and an API secret — combined as:

Authorization: Bearer <client_id>:<api_key>:<api_secret>

The CLI and MCP server build this header for you once you are signed in. You only need it directly when calling the API with curl or your own HTTP client. Throughout this manual that token is written as $TOKEN.

Workspaces

Most tools act against a workspace. The CLI and MCP server store credentials per workspace and load the one named default unless you pass -w / --workspace (CLI) or a workspace argument (MCP tools). Sign in once per machine and every mail command reuses the stored token.

Scoping and safety

Every authenticated request is scoped to the workspace it was issued for — your token cannot reach another workspace's mailboxes or messages. On top of that, SpiderMail's security layer scans inbound mail for prompt injection and blocks outbound credential leaks regardless of who is calling.

Keep your token safe

Treat the token like a password:

  • Store it as a secret in CI, never in committed code.

  • Do not paste it into shared chats or logs.

  • If it is exposed, rotate it.

Warning: The token grants full access to your connected mailboxes — reading, sending, and deleting. Guard it like mailbox credentials, because effectively it is.

Next steps

  1. Quickstart — connect a mailbox and send.

  2. Build with AI Agents — wire the token into an MCP client.

  3. API Reference — the endpoints the token unlocks.