# Agent access & tokens

> Separate credentials, clear permissions, and accountable changes.

## Your login and your agent’s token

Your browser login gives you access to your account, workspaces, settings and record viewer. Each agent connects separately using an **MCP bearer token**. Your account password is never the MCP token, and an agent token cannot sign in to your browser account.

GitHub, Google and Microsoft sign-in use OAuth for your browser account when available. ChatGPT and Claude can separately authorise MCP access through Orbit’s OAuth flow. Hermes and other clients can continue using manually issued bearer tokens.

## Connect ChatGPT or Claude

Start in [ChatGPT](/docs/connect-chatgpt) or [Claude](/docs/connect-claude), add Orbit’s MCP endpoint and sign into Orbit to approve access. Select workspaces and a reader or contributor role. Each approval creates a separate agent connection; no manual token is displayed. You can change its permissions or revoke it in Agents.

OAuth uses authorisation codes with PKCE, one-hour access tokens and rotating refresh credentials with a 30-day lifetime. Revoked connections and unavailable accounts cannot access records or exchange pending codes and refresh credentials. Browser social sign-in remains a separate feature.

## Create manual token access

From your account, choose **Connect an agent**. Select a name, permitted workspaces and a role, then confirm your identity. Copy the token immediately and store it in your agent client’s secret settings. It is shown once; if you lose it, replace it.

The connection page provides the correct endpoint and client configuration. Requests use an `Authorization: Bearer YOUR_TOKEN` header over HTTPS. See [Connect Hermes](/docs/connect-hermes) for a complete example.

## Choose a role

| Role | Access |
| --- | --- |
| View only (`reader`) | Search and retrieve permitted records, context, field definitions and task history. |
| View and edit (`contributor`) | Reader access plus record creation, updates, archive/restore, activity and task operations. |

Neither role can manage your account, create workspaces or issue agent credentials. Workspace exports are available to you in **Settings**, not as an MCP tool. The [tool reference](/docs/mcp-tools) lists each role’s tools.

## Choose workspaces

A token can access selected workspaces with a role for each, all current workspaces as a snapshot, or all current and future workspaces with a common role. All-workspace access only covers workspaces belonging to your account; it never grants another customer’s data.

Agents call `workspaces_list` to discover their access, then include `workspace_id` in record calls. A token with several grants still has to target a workspace explicitly. Records and relationships cannot cross workspace boundaries.

## Change or revoke access

Open the agent in your account to change permissions, **Replace token**, or **Revoke access**. Sensitive changes require your password or recent confirmation through a linked provider for accounts without a password.

OAuth connections reconnect through their client instead of using **Replace token**. Replacing a manual token preserves the agent identity and attribution while immediately invalidating its previous credential. Update the secret in your client and reconnect. Revocation permanently disables that agent identity; create a new agent if it needs access again. Records remain in Orbit.

Permission changes affect subsequent requests. Work already in flight may finish, and task claims retain their normal expiry. The last accepted request is historical connection evidence, not a continuous online indicator.

## Keep tokens private

Use a separate credential per agent so access and attribution remain clear. Give each one only the permissions it needs. Do not put tokens in chat prompts, source control, screenshots or shared logs. Replace a token immediately if it is exposed.

Reading a record or receiving a task does not authorise an external action. Your agent’s workflow must separately govern sending messages, making calls and changing other systems.