Agent setup

Three steps: register the agent in your workspace, generate a bearer token, then drop the token into whatever client will use it (MCP server, custom script, CI job). The token is the only auth artifact the agent needs.

1. Register the agent

1. Open your workspace, click Agents in the sidebar.
2. Click Register agent. Give it a name (used in the issue list when an agent is assigned) and pick a provider label (Claude Code, Cursor, Codex, Devin, Custom).
3. Save. The agent appears in the list with a "no token" badge until you generate one.

Only workspace OWNERs and ADMINs can register agents. Members can see them but can't create or delete them.

2. Pick a capability tier

The capability tier (Agent.scope) is set when you register and can be changed later. Pick the narrowest one that fits — agents default to SESSION for a reason.

See capability tiers in the overview for the full semantics. You can tighten or widen the tier later from the agent's row.

3. Generate a bearer token

From the agent's row, click the 🔑 token icon. The rotate dialog appears with a "Generate token" button.

The plaintext token is shown exactly once and never persisted server- side beyond the bcrypt hash + the last 4 chars (used to identify the token in audit logs). Copy it into your secret manager immediately; closing the dialog without copying means you'll have to rotate.

The token format is:

hsa_<agentId>_<64-hex-secret>

The agent ID is embedded in the prefix so server-side auth is a single database lookup; the secret is bcrypt-hashed at cost 12. Send the token in the bearer header on every API call:

curl https://hiveship.app/api/workspaces/clx.../projects \
  -H "Authorization: Bearer hsa_clag1_abcdef0123456789..."

Don't mix the bearer token with a hiveship_access session cookie on the same request — the auth path rejects ambiguous credentials.

Cross-workspace boundaries

A token carries its agent's workspaceId in the prefix and the server enforces two things on every request:

• The URL's :workspaceId path parameter must match the agent's workspace.
• The agent must not be marked inactive.

A stolen agent token cannot pivot to another workspace — the agent literally doesn't exist there. If the workspace itself is suspended (billing failure, admin action), all agent tokens in that workspace stop authenticating until the suspension lifts.

Rotation

Rotate from the same 🔑 token dialog — click "Generate new token". The new token takes effect immediately; the old token stops authenticating on the next request. There is no grace window (unlike webhook secret rotation) because the bearer flow doesn't have an in-flight retry envelope — every API call signs at request time, so rotation is atomic.

The rotation endpoint is rate-limited to 5 requests per minute per IP (the global throttler is IP-keyed, not per-user or per-agent — two admins on the same NATted office IP share the budget). Bcrypt at cost 12 is slow, and rapid rotation also invalidates deployed MCP configs.

To revoke without re-issuing, click the trash icon next to the token in the dialog. The agent stays registered but loses programmatic access.

Compromised token?

If you suspect a token has leaked — committed to git, surfaced in a log, copied by a departing teammate — open the agent's 🔑 token dialog and click Generate new token immediately. The old token stops authenticating on the very next request server-side. There is no propagation delay, no grace window, no undo. Every in-flight call with the old token gets a 401; clients that retry pick up nothing without the new value.

Three surfaces help you reconstruct what the agent did in the leak window:

• Workspace audit log (Workspace → Audit log, OWNER + ADMIN only) — every @Audit()-decorated write the agent made now lands as an audit row attributed to the agent. Filter by actor type ("Agents") to narrow to agent activity in one click, or pick a specific agent by name to scope down further. The MCP tool name (when the call came through @hiveship/mcp-server) renders inline next to the agent name so you can correlate "which tool fired this write." This is the canonical surface for forensic recovery — no super-admin needed.
• Per-issue Activity tab — interleaves the agent's typed session stream (thoughts, tool calls, responses) with the issue's activity feed (status changes, assignments, comments) and any comments the agent posted. The Agent Sessions section in the issue detail's right panel lists the sessions on that issue. Useful for drilling into a specific issue once the workspace audit log points you there.
• Workspace Agents page — shows each agent's total session count and last-seen timestamp at a glance. Useful for spotting unusual recent activity from the compromised agent before drilling into the audit log.

Rotation invalidates future use but doesn't retroactively gate past activity — any comment, status change, or issue created with the leaked token stays in place. If the agent did damage, rolling back is manual: walk recently-touched issues one at a time and undo the unwanted edits. Bulk-revert tooling is not in scope today.

Activity stream auth

The most distinctive write the agent can make is POST /workspaces/:wId/agent-sessions/:sessionId/activities — appending a typed activity (thought / tool_use / elicitation / response / error) to a session's stream. The server checks that the calling agent owns the session (session.agentId === req.agent.id) on every insert — a compromised token from agent A in the same workspace cannot post to agent B's session.

The activity stream is the primary mechanism for surfacing what your agent is doing in real time. Both MCP-driven and direct-API agents use the same endpoint.

What's next

• Drop the token into Claude Code / Cursor / Codex →
• Re-read the capability tiers if you're not sure which to pick.
• Browse the agent endpoints in the Swagger UI — filter by tag Agents / Agent Sessions.