One credential per agent
Tokens bind an authenticated agent to a workspace and role. Orbit generates a random secret, displays it once, and stores only a SHA-256 hash.
Workspace owners can create, replace and revoke tokens in the account interface, with password confirmation. Server administrators can also issue tokens through a secure terminal on the application host:
php artisan orbit:agent-issue Hermes --role=contributor --no-interaction
Keep the returned agent ID. Store the token in the client’s secret source rather than in a conversation or repository. Avoid issuing tokens through a command runner that retains its output in shared logs.
Choose the right role
Reader can discover the workspace, search contacts, and retrieve accessible records. It is the default role.
Contributor has reader access and can manage contacts, organisations, projects, relationships, and tasks with owner-checked claims; append/link activities; apply tags; and populate registered custom fields. Only administrators can define fields, export workspace data, or redact activity through the CLI.
Owner is a browser account that manages credentials for its workspace. Server administration, field definitions, export and redaction remain CLI responsibilities. Neither owner nor administrator is an MCP role; agent tokens cannot gain those permissions.
Permissions apply both to discovery and execution. Calling a hidden tool directly cannot bypass the reader restriction.
Rotate a token
php artisan orbit:agent-rotate AGENT_UUID --no-interaction
Save the replacement secret and update the agent’s connection. The previous token becomes invalid immediately. The identity and attribution history remain intact.
Revoke an agent
php artisan orbit:agent-revoke AGENT_UUID --no-interaction
Revocation blocks subsequent authentication without deleting historical attribution. Requests already in progress may finish. A revoked identity cannot be reactivated; issue a new agent credential instead.
Secure the connection
Use HTTPS for remote access. Keep ORBIT_REQUIRE_HTTPS=true, and keep PostgreSQL off the public network. Browser origins are rejected unless explicitly allowlisted through ORBIT_ALLOWED_ORIGINS; Hermes normally makes non-browser requests without an Origin header.
OAuth is not implemented in this milestone. The selected Hermes client supports configured bearer credentials. Reassess the authentication flow before adding a client that requires OAuth.
An unexpired claim held by a revoked agent remains reserved until its lease expires (at most one hour). Revocation does not confirm that external work stopped; inspect attempt history and external side effects before reclaiming.