Connected Apps

Revoke a connected app

Requires scope: manage. 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. 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.

delete/v1/oauth/grants/{id}

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/oauth/grants/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

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

Response

The revoked app, with what it left behind.

idstring required

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

client_idstring required

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

client_namestring nullable required

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

first_partyboolean required

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

scopestring required

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

scopesstring[] required

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.

created_atstring date-time required

When the app was first approved.

approved_atstring date-time required

When it was last approved before this revoke.

last_used_atstring date-time nullable required

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

created_api_keysinteger required

API keys it created that still work after the revoke.

created_webhooksinteger required

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

signing_secrets_knowninteger required

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

revoked_atstring date-time required

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

Changes

No recorded changes to this operation across all 1 revision of this API.