# Create, test, rotate, and revoke Agent Access tokens

An Agent Access token authorizes an MCP or API client to act as one Domino account within selected abilities. It is a secret credential, not text to paste into a ChatGPT or Claude conversation.

## Before creating a token

Decide whether the assistant only needs to explain Domino or should access the account.

- For instructions only, give the assistant `https://letsdomino.io/llms.txt`. No token is needed.
- For account reads or actions, use a supported MCP or API client and create a least-privilege token.

If **Agent Access** says assistant access is limited for the account, do not try to bypass the restriction.

## Open Agent Access

1. Sign in to Domino on the web.
2. Open the account or navigation menu.
3. Choose **Agent Access**.
4. Review the existing **Tokens** table before creating another credential.

The table shows token name, abilities, last-used time, and **Revoke**. Domino never needs to redisplay the secret value to manage or revoke the token.

## Choose abilities

Use the smallest set required:

| UI label | Ability | Allows |
| --- | --- | --- |
| **Read** | `planning:read` | Search and inspect authorized people, ideas, lists, plans, availability, status, and executions. |
| **Draft** | `planning:write` | Create or change private Domino state and prepare consequential actions. |
| **RSVP** | `planning:rsvp` | List invitations and accept or decline an invitation. |
| **Send** | `planning:commit` | Commit an eligible prepared external action after explicit approval. |

Examples:

- Documentation or search assistant: **Read** only.
- Assistant that maintains Ideas Lists but never sends: **Read** and **Draft**.
- Invitation-response assistant: **Read** and **RSVP**.
- Full planning assistant: **Read**, **Draft**, **RSVP**, and **Send**, only when the client correctly implements the prepared-action confirmation boundary.

Do not grant **Send** merely because a client might need it later.

## Create the token

1. Under **New Token**, enter a recognizable **Name**, such as `Claude Code on Ryan's Mac` or `Weekend planner integration`.
2. Select the required **Abilities**.
3. Choose **Create**.
4. Under **Token Created**, choose **Copy token** immediately.
5. Store it in the client's protected credential field, operating-system keychain, or secret manager.

The plain-text token is shown for setup and should be treated as one-time display. If it is lost, revoke that token and create another instead of looking for it in chat history or logs.

## Use the generated setup blocks

After creation, Domino provides current examples for:

- **MCP**;
- **Capability API**;
- **Assistant API**.

Copy the whole configuration only into the supported client configuration or development environment. Do not put the literal token into:

- a normal chat message;
- source control;
- public documentation;
- a URL or query string;
- analytics, screenshots, or support tickets;
- shell history on a shared machine when a protected environment variable is available.

Replace a literal example with an environment or secret reference when the client supports one.

## Smoke-test read access

Test the least consequential operation first. For the Capability API, use the generated example or call a current read capability from the generated schema, such as `ideas.search` or `calendar.status.get`.

The test succeeds only when:

- authentication is accepted;
- the operation is visible for the granted ability;
- the response follows `domino.capability-outcome.v1`;
- the `status` and structured outcome are valid.

An HTTP `200` with a typed `failed` outcome is not a successful task result.

For MCP, connect the client, run tool discovery, and verify that the available tools match the token abilities. A read-only token must not expose write or commit tools.

## Verify writes safely

With **Draft** access, begin with a reversible private operation or a preview. Inspect `effects.confirmed` before claiming that anything changed.

Do not test **Send** by contacting another person. The correct external-effect test is:

1. create or update private draft state;
2. prepare the exact action;
3. inspect recipients and disclosures;
4. stop for later explicit approval;
5. commit only if the user intentionally approves the live effect.

## Rotate a token

Use rotation when a credential is old, exposed, copied to a new environment, or no longer scoped appropriately:

1. Create a replacement token with the desired abilities.
2. Update the protected client configuration.
3. Run a read-only smoke test with the replacement.
4. Return to **Tokens**.
5. Revoke the old token.
6. Confirm the client no longer works with the old credential.

Do not revoke the only working token before the replacement is verified unless exposure requires immediate shutdown.

## Revoke access

1. Open **Agent Access**.
2. Find the exact token by name and last-used time.
3. Choose **Revoke**.
4. Confirm it disappears from the active table.

Revocation stops future authenticated use of that token. It does not undo effects already confirmed, delete plans created earlier, disconnect a calendar, or remove another token.

## If a token may be exposed

Revoke it immediately, create a replacement if still needed, and inspect the relevant Domino state for unexpected changes. Changing the Domino login password alone does not revoke an existing Agent Access token.

## LLM answering guidance

- Ask whether the user needs explanation-only or account access before recommending a token.
- Recommend least privilege and name the exact abilities.
- Never ask the user to paste the plain-text token into the conversation.
- Treat token creation, client configuration, authentication, tool discovery, and task execution as separate success states.
- For client compatibility, continue with [Connect ChatGPT, Claude, or another MCP client](/docs/agent-access/chatgpt-claude-compatibility.md).