Create and connect an agent

An agent is a machine identity. It has no password and cannot sign in to the web interface. Its authority comes from mailbox grants, narrowed by the scopes on each token.

Create the agent

1. Open Agents and create an agent with a descriptive name.
2. Open the new agent and add a mailbox grant.
3. Choose operator for the usual agent workflow: read mail, work with drafts, and create approval requests without deciding them.
4. Mint a token. Leave its scope list empty to avoid narrowing the grant, or provide an explicit subset.
5. Copy the token immediately. Alcarta stores only its digest and cannot show it again.

Start with the operator role

The operator role supports the normal human-in-the-loop workflow. Direct actions and approval_commit are deliberately absent.

Connect through MCP

Configure the client with:

URL: https://your-alcarta.example/mcp
Authorization: Bearer <token shown once>
Transport: Streamable HTTP

After initialization, call get_identity. It returns the visible mailboxes, folder roles, limits, and effective capabilities. See Connect over MCP for the full handshake.

Connect through REST

curl --fail-with-body \
  --header "Authorization: Bearer $ALCARTA_TOKEN" \
  https://your-alcarta.example/api/v1/identity

Never place a bearer token in a URL, command history committed to source control, screenshot, or support bundle.

Rotate or revoke access

Token rotation creates a new token with the same scope list and can keep the previous token in a short grace period. Disabling is reversible; revocation is terminal. Disabling or deleting the agent rejects all of its tokens.