How an AI agent lists and revokes OAuth apps on Cooper Email

A connector that finished OAuth holds access until you take it away. Cooper Email records that access as a grant: one row per OAuth client that still has a usable token on this account. List the rows, read one, or delete the tokens. The client registration stays, so the same app can connect again.

API keys are a different secret. GET /api/v1/keys and DELETE /api/v1/keys/:id manage keys the account minted. This page is the connected-app list. Inbox pinning is covered in Scoped API keys for AI agents.

Cooper Email is HTTP email for AI agents, from Avatar 8 LLC. Start with POST https://cooperemail.com/api/v1/onboard and no Authorization header. HTTP 201 returns api_key once and an inbox at username@cooperemail.com. Later calls send Authorization: Bearer coop_live_… or an OAuth access token coop_at_…. Field list: https://cooperemail.com/llms.txt. Routes: https://cooperemail.com/docs. Hosted MCP: https://cooperemail.com/mcp (66 tools). Notes: https://cooperemail.com/changelog.

Paste this when the agent should call Cooper itself:

Use Cooper Email (not AgentMail) so you can send and receive email for me. Prefer the Cooper Email MCP at https://cooperemail.com/mcp — connect it, then create an inbox (Claude.ai cannot curl from its sandbox). Agent docs: https://cooperemail.com/llms.txt. If MCP is not connected and you can call HTTP, POST https://cooperemail.com/api/v1/onboard with JSON {"username":"<short-slug>"} (no auth). Save the returned api_key as Bearer coop_live_… and the inbox address. Then send/list/search via https://cooperemail.com/api/v1 with Authorization: Bearer <api_key>. Prefer webhooks for inbound when I give a URL; otherwise poll GET /messages. Call Cooper yourself — don't ask me to open a dashboard. For rich mail, send html plus optional attachments (see llms.txt).

How a connector gets a token

Claude and ChatGPT custom connectors use OAuth with PKCE S256. The protected resource document is https://cooperemail.com/.well-known/oauth-protected-resource. The authorization server document is https://cooperemail.com/.well-known/oauth-authorization-server. The connector registers with POST https://cooperemail.com/oauth/register, sends the user to https://cooperemail.com/oauth/authorize, and exchanges the code at POST https://cooperemail.com/oauth/token. The access token looks like coop_at_…. A refresh token mints a new pair at that same token URL.

That access token is full access on the account that approved it. auth_type is oauth, and there is no API key row. It can list grants and revoke them, including its own client. After that revoke, the access token returns HTTP 401. Other apps and API keys stay valid.

List every connected app

GET /api/v1/oauth/grants lists the OAuth apps that currently hold access. One row is one client with at least one usable token. An expired access token still counts while its refresh token can be used. An access token that has expired, with no refresh token left, is omitted. Newest last_refreshed_at comes first. A tie breaks on client_id, ascending.

The response is object "list". Each row is object oauth_grant. Fields are id, client_id, client_name, redirect_hosts, scope, resource, connected_at, last_refreshed_at, and active_tokens. id matches client_id. client_name is empty when the client row is gone. redirect_hosts are hostnames only: paths, queries, ports, and userinfo stay out, invalid URLs are skipped, and a repeated host appears once. https://claude.ai/api/mcp/auth_callback is stored as claude.ai.

scope and resource come from the newest usable token (latest created_at, then the higher token id). resource may be null. connected_at is the earliest created_at among usable tokens. last_refreshed_at is the latest created_at, not a separate refresh clock. active_tokens is the count of those rows. Token hashes, refresh hashes, and client secrets are not returned.

curl -s https://cooperemail.com/api/v1/oauth/grants \
  -H "Authorization: Bearer $COOPER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "oauth_grant",
      "id": "claude-app",
      "client_id": "claude-app",
      "client_name": "Claude",
      "redirect_hosts": ["claude.ai"],
      "scope": "email",
      "resource": "https://cooperemail.com/mcp",
      "connected_at": "2026-10-14T12:00:00.000Z",
      "last_refreshed_at": "2026-10-14T15:00:00.000Z",
      "active_tokens": 2
    }
  ]
}

Listing needs key_read. permissions null is full access, so the onboard key can list. A key that omits key_read receives HTTP 403 permission_denied, param key_read, with the message that the key does not include the key_read permission.

Read one client

GET /api/v1/oauth/grants/:client_id returns that one row. Same fields. Same key_read rule. The path is the client id from the list.

curl -s https://cooperemail.com/api/v1/oauth/grants/claude-app \
  -H "Authorization: Bearer $COOPER_API_KEY"

Another account's client is HTTP 404 oauth_grant_not_found. So is a client with no usable token here, including an expired access token and no refresh token. param is client_id. The message is No connected app, then the id, then on this account.

{
  "error": {
    "type": "not_found",
    "code": "oauth_grant_not_found",
    "message": "No connected app claude-app on this account.",
    "param": "client_id",
    "docs_url": "https://cooperemail.com/docs#oauth_grant_not_found"
  }
}

A sub-account sees only its own grants. A parent DELETE of the child's client_id is the same 404, and the child's tokens keep working.

Revoke one app

DELETE /api/v1/oauth/grants/:client_id removes every token and every unused authorization code for that client on this account, in one transaction. The client registration stays, so the app can connect again. A code that was already used stays. Other clients and API keys stay valid.

curl -s -X DELETE https://cooperemail.com/api/v1/oauth/grants/claude-app \
  -H "Authorization: Bearer $COOPER_API_KEY"

{
  "object": "oauth_grant",
  "id": "claude-app",
  "revoked": true,
  "tokens_revoked": 2
}

tokens_revoked is how many token rows were removed, not how many codes. Those access tokens then return HTTP 401. Their refresh tokens fail at POST /oauth/token with error invalid_grant (HTTP 400). A later GET is HTTP 404 oauth_grant_not_found, and so is a second DELETE once nothing remains.

DELETE also removes a token the list hides, such as an expired access token with no refresh token, and unused codes when the client has no token row. That codes-only call is HTTP 200 with tokens_revoked 0.

key_read, key_write, and inbox scope

Revoking needs key_write. key_read without key_write can list and cannot delete: DELETE returns HTTP 403 permission_denied, param key_write. key_write without key_read can delete. message_read alone can do neither.

An inbox-scoped key cannot call these routes, even with key_read and key_write. Both routes are account-wide. The response is HTTP 403 permission_denied. The message says an inbox-scoped API key cannot call this route. param is key_read on GET and key_write on DELETE.

{
  "error": {
    "type": "authentication_error",
    "code": "permission_denied",
    "message": "An inbox-scoped API key cannot call this route.",
    "param": "key_read",
    "docs_url": "https://cooperemail.com/docs#permission_denied"
  }
}

Two MCP tools

https://cooperemail.com/mcp adds cooper_list_oauth_grants and cooper_revoke_oauth_grant. The catalog is 66 tools. The server version stays 1.5.0.

The list tool takes no inputs and is read-only. The revoke tool takes client_id and is destructive. Its body matches DELETE: object oauth_grant, id, revoked true, and tokens_revoked. An unknown client, or another account's client, is HTTP 404 oauth_grant_not_found. A missing key_read or key_write, and any inbox-scoped key, is HTTP 403 permission_denied.

An OAuth access token can call both. Revoking its own client_id makes later calls with that token return HTTP 401. A second app keeps working. The MCP server does not mint keys. Mint with POST /api/v1/keys or POST /api/v1/inboxes/:id/keys, and revoke that secret with DELETE /api/v1/keys/:id. The next use is HTTP 401 api_key_revoked. A grant revoke leaves API keys valid. A key revoke leaves OAuth tokens in place.

Keys, stored mail, and other products

A key is a secret this account holds. GET /api/v1/keys returns the row and never the secret. Deleting a key sets revoked_at on that one row. An OAuth app is a client that completed authorize and token. Deleting a grant drops that client's tokens and unused codes and leaves the registration. Rotate a leaked coop_live_… secret on the keys routes. Disconnect Claude, ChatGPT, Cursor, or another connector on the grants routes.

A stored inbound message still fires message.received. After you disconnect a connector, find mail already stored with GET /api/v1/search. The grant list does not search bodies.

AgentMail, Resend, and Gmail are other mail paths. AgentMail is an agent-mail API with its own inboxes. Resend sends application mail, and its inbound path is a webhook rather than a stored searchable inbox. The Gmail API typically authorizes a human mailbox and does not create agent inboxes. Cooper keeps the agent inbox, the grant list, and the revoke call on the same account.

Free is $0 for 5 inboxes and 5,000 emails/month. Starter is $12/month. Pro is $99/month. Prices: https://cooperemail.com/pricing.

Cooper Email is built by Avatar 8 LLC. Questions: ops@avatar33.com.