Agent registration
An agent in a terminal or a chat can get API access without an API key. It asks for access with your email address, and you approve it on shipmail.to with a 6-digit code.
Last updated
How it works
- The agent registers with your Shipmail sign-in address.
- It shows you a link and a 6-digit code.
- You open the link, sign in, type the code, choose one organization and the permissions, and approve.
- The agent receives a one-hour access token and a 30-day identity assertion.
Shipmail follows the auth.md profile, version 0.6.0, with the service_auth method only. Agents find the endpoints in the agent_auth block of /.well-known/oauth-authorization-server.
Register
/api/agent/identity{
"type": "service_auth",
"login_hint": "you@example.com",
"agent_name": "Release bot"
}The response holds a claim_token and a claim block with the user_code and verification_uri to show the person. It looks the same whether or not the address has an account. The agent name is shown on the approval page as unverified.
Approve the request
To approve, you sign in to a Shipmail account that has the requested address among its verified sign-in addresses. If two-factor authentication is on, finish it first. Signing in with a mailbox password won't work. Five wrong codes deny the request.
You pick exactly one organization and the permissions, as on the OAuth consent page. Send permissions are never preselected. The agent then appears in Developer, then Connections, where you can change or disconnect it.
If the organization has no domain yet, the page starts with the Set up permissions. They let the agent add domains and mailboxes and read their configuration. Set up can't read or send mail, issue passwords, or pay. If you signed up through the agent's link, the page first asks for your name and your organization's name.
Set up Shipmail
An agent can set Shipmail up for you, but it never pays. It asks what you need, suggests a plan, and waits for your approval. Then it sends you a billing link for your organization:
https://shipmail.to/billing?org=<organization id>&plan=<solo|pro|team|scale>&interval=<monthly|annual>&mailboxes=<n>- The page shows the organization, the plan marked as suggested by your agent, the total, the renewal, and the trial terms. Nothing changes until you confirm and pay.
- Only the organization owner can pay. An Admin sees a link to send to the owner. An organization that already has a plan goes to the plan change and capacity flows in Billing.
- After payment, a page shows Activating until Shipmail has recorded it, then tells you to return to your agent. The agent checks
GET /v1/organization/accessand continues. - A domain purchase from an agent is never charged. The API answers with
reason: "owner_confirmation_required"and anaction_urlwhere you review the price and confirm.
Get tokens
The agent polls the token endpoint every 5 seconds with the claim grant:
curl https://shipmail.to/api/auth/oauth2/token \
-d grant_type=urn:workos:agent-auth:grant-type:claim \
-d claim_token=clm_...After approval it receives access_token, identity_assertion, and assertion_expires. The claim token works once, plus a second time within 120 seconds if the response was lost. When the access token expires, the agent exchanges the assertion for a new one:
curl https://shipmail.to/api/auth/oauth2/token \
-d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
-d assertion=<identity_assertion> \
-d resource=https://shipmail.to/api/v1Use resource=https://shipmail.to/api/mcp for a token for the hosted MCP server. The agent sends the access token as Authorization: Bearer, like any OAuth access token. A token sent to the wrong one gets a 401 that names the resource it needs, so the agent exchanges the assertion again rather than registering from scratch.
The token's scope lists the API scopes you approved, and the token can use only those. It follows the same rule as other OAuth access tokens.
Revoke
The agent can revoke one access token at /api/auth/oauth2/revoke (RFC 7009). Disconnecting the agent in Developer, then Connections ends the registration, its identity assertion, and every access token at once. Reconnecting never revives them; the agent registers again.
Errors
| Code | Meaning |
|---|---|
| anonymous_not_enabled | Anonymous registration is off. Use service_auth. |
| issuer_not_enabled | No identity providers are trusted. Use service_auth. |
| invalid_login_hint | login_hint is not an email address. |
| invalid_claim_token | The claim token is unknown. Register again. |
| claimed_or_in_flight | The person already approved. Poll the token endpoint. |
| claim_expired | The 24-hour claim window closed. Register again. |
| authorization_pending | The person has not approved yet. Keep polling. |
| slow_down | You polled faster than every 5 seconds. |
| expired_token | The code expired. Restart the claim for a new code. |
| access_denied | The person denied the request, or 5 codes were wrong. |
| invalid_grant | The claim token, assertion, or connection is no longer valid. |
| invalid_target | resource is neither the REST API nor the MCP server. |
| rate_limited | Too many registrations, restarts, polls, or exchanges. Wait and retry. |
Frequently asked questions
Does Shipmail send an email when an agent registers?
No. The agent shows the person a link and a 6-digit code. The person signs in on shipmail.to and types the code there. Shipmail never asks anyone to enter a code they received from someone else.
What can the agent do after approval?
Only what the person chose on the approval page, in one organization, and never more than the person can do. Send permissions are never preselected. The choices can be narrowed later from Developer, then Connections.
How long do the credentials last?
Access tokens last one hour. The identity assertion that renews them lasts 30 days. After that the agent registers again and the person approves again.