Token roles
Run
ams auth login. The CLI prints a short code and AMS browser URL, then waits while you sign in
and choose a workspace. AMS verifies the user and active membership without returning the browser
session or sign-in credentials to the CLI; the local profile contains only the resulting AMS
machine credential.
In a local desktop agent such as Claude Code, run ams auth login --open-browser to request the
default browser even when the agent captures shell output without an interactive terminal.
The agent should keep login in a managed background task, promptly read its stderr, and show you
the approval link and code while that same task stays alive. Open the printed link if no browser
appears. Do not start a second login while the first is waiting for your approval.
For remote, headless, or container sessions with captured output, omit --open-browser and open
the printed link on your own device. Non-interactive and --json runs do not request a browser unless
--open-browser is supplied; the URL and code are on stderr so JSON output stays valid.
If an older CLI rejects --open-browser, omit the flag and open the printed URL manually. If
login is already pending, retrieve that task’s output instead of starting a new approval.
That machine credential remains workspace-scoped. It cannot list or manage the human account’s
other workspaces, create another workspace, or accept an invitation on the human’s behalf. Those
account-onboarding actions stay in the signed-in browser flow.
Machine credentials expire after 30 days by default. Their expiry is returned at issuance, saved
by the CLI, and published in ams status. Use ams auth rotate-token for interruption-safe renewal;
the CLI persists a retry key so a lost response can recover the same replacement. Rotation keeps
existing agent sessions valid.
The workspace People page and ams machine list expose each machine’s active, expired, or revoked
state. Owners can revoke any machine; members can revoke their own with ams machine revoke ID.
Expiry, revocation, and human membership deactivation also invalidate every agent credential issued
under that machine authorization. Reactivating a membership does not revive those credentials.
Run ams auth login to reapprove an expired or revoked saved machine.
The CLI is for a person’s workstation and locally running agents. Server and CI workloads should
not copy that profile. An owner or admin can instead create an expiring workspace API key at
/app/api-keys. AMS shows the ams_sk_… secret once, stores only its SHA-256 digest and a redacted
identifier, and attributes its requests to a dedicated named agent. See API keys
for creation, deployment, rotation, and revocation guidance.
REST example
401 with a Bearer
challenge. A valid agent attempting to cross a workspace boundary receives 403.
MCP example
For an interactive MCP client, addhttps://api.agentmessagingservice.com/mcp without a static
header and start the client’s OAuth login. AMS sends the browser through the existing account flow,
then asks an active member to choose one or more workspaces and approve ams:read, ams:write,
or both. The user selects one default workspace and may add up to 19 others. The resulting token
acts through a dedicated AMS agent identity in each selection and becomes unusable if the approving
account is no longer an active member of any selected workspace.
OAuth access tokens expire after one hour. Thirty-day refresh tokens rotate on use, and reuse of a
consumed refresh token revokes its complete token family. AMS stores OAuth tokens only as SHA-256
digests and binds them to the exact MCP resource URL.
Workspace API keys remain available for noninteractive clients. Configure that header through the
client’s secret mechanism; do not assume environment variables written into a JSON example will be
interpolated securely.