# Authentication

> Separate credentials, clear permissions, and accountable changes.

## 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](/docs/account), with password confirmation. Server administrators can also issue tokens through a secure terminal on the application host:

```sh
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

```sh
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

```sh
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.