Skip to main content
Get Started
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.connected_apps.revoke(
  "oag_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "id": "oag_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "client_id": "<client_id>",
  "client_name": "<client_name>",
  "first_party": false,
  "scope": "<scope>",
  "scopes": ["send"],
  "created_at": "2026-10-04T12:00:00.000Z",
  "approved_at": "2026-10-04T12:00:00.000Z",
  "last_used_at": "2026-10-04T12:00:00.000Z",
  "created_api_keys": 0,
  "created_webhooks": 0,
  "signing_secrets_known": 0,
  "revoked_at": "2026-10-04T12:00:00.000Z"
}

Revoke a connected app

Ends the sign-in, as Revoke in Settings › Connected apps does: every access and refresh token it was issued stops working at once, and the app has to be approved again to get back in.
DELETE/v1/oauth/grants/{id}scope · manage
import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.connected_apps.revoke(
  "oag_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);
{
  "id": "oag_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "client_id": "<client_id>",
  "client_name": "<client_name>",
  "first_party": false,
  "scope": "<scope>",
  "scopes": ["send"],
  "created_at": "2026-10-04T12:00:00.000Z",
  "approved_at": "2026-10-04T12:00:00.000Z",
  "last_used_at": "2026-10-04T12:00:00.000Z",
  "created_api_keys": 0,
  "created_webhooks": 0,
  "signing_secrets_known": 0,
  "revoked_at": "2026-10-04T12:00:00.000Z"
}

Path Parameters

idstringrequired

The connected app's id (oag_…), from List connected apps.

The API keys and webhook endpoints it created, and the webhook signing secrets it was shown, stay; the response counts them, so revoke and rotate those yourself. (Only when one of its refresh tokens is used twice, a sign of theft, does mails.ai remove them as well, and rotate those secrets again.) Idempotent: revoking an app already revoked returns its existing revoked_at. Closed to apps connected by sign-in (403 connected_app_not_allowed), and to a key tied to one agent (403): use an API key with manage that is not tied to an agent, or the mails CLI.

Response

idstring

The sign-in's id (oag_…): the id in the path.

client_idstring

The app's OAuth client id: the id it registered with, or the address of its client-ID document.

client_namestring | null

The name the app gave itself, at most 80 characters, or null when it gave none; mails CLI for the mails CLI.

first_partyboolean

true for the mails CLI, false for an app somebody connected by signing in.

scopestring

What the person had approved: full_access, send or read.

scopesstring[]

What its tokens could do until the revoke, in the API key scopes: full_access = send + read + manage, send = send + read, read = read. Never more than the role of the person who approved it gave an app: a Member's apps never hold manage, and a Billing member's hold read only.

One of: send, read, manage

created_atstring

When the app was first approved.

approved_atstring

When it was last approved before this revoke.

last_used_atstring | null

When one of its tokens was last used, recorded at most once a minute. Null when none was used.

created_api_keysinteger

API keys it created that still work after the revoke.

created_webhooksinteger

Webhook endpoints it created, still in place after the revoke.

signing_secrets_knowninteger

Other webhook endpoints still signing with a secret it was shown.

revoked_atstring

When the sign-in was ended and its tokens stopped working. For one that was already revoked, the time it ended then.

Was this page helpful?