Skip to content
clearance.rest

Authorization links

An authorization link is a URL you create and send to the owner of a mailbox. It opens a hosted page, under your branding, where they choose Gmail or Outlook, grant access on the provider’s own page and land on a result page. The mailbox is then connected to your project. The person needs no account and you never handle their credentials.

https://links.clearance.rest/<token>
Section titled “Create a link”
curl -X POST https://api.clearance.rest/emails/auth-links \
  -H "X-API-Key: $CLEARANCE_REST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "expires_in": 86400,
    "max_uses": 1,
    "providers": ["gmail"],
    "locale": "en",
    "return_url": "https://app.example.com/done",
    "metadata": { "customer": "c1" },
    "branding": { "name": "Acme", "primary_color": "#112233" }
  }'

Every field is optional:

Field
expires_in Seconds the link stays valid. Default 7 days, at least 1 hour, at most 30 days.
max_uses How many mailboxes can be connected with it. Default 1. 0 means unlimited until the link expires.
providers A subset of ["gmail", "outlook"] to offer. Default both.
locale The language of the page: en (default) or tr. The visitor can switch it.
return_url Where the result page sends the visitor back to. Its origin must be in the project’s allowed return origins (project Settings).
metadata JSON stored on every mailbox connected through the link, up to 16 KB.
branding name (up to 100 characters), logo_url (https), description (up to 500), primary_color (#RRGGBB).

The response is the link:

{
  "success": true,
  "id": "0190...",
  "url": "https://links.clearance.rest/3f9c...",
  "status": "active",
  "expires_at": "2026-11-01T10:00:00.000Z",
  "max_uses": 1,
  "use_count": 0,
  "providers": ["gmail", "outlook"],
  "locale": "en",
  "return_url": null,
  "branding": { "name": null, "logo_url": null, "description": null, "primary_color": null },
  "metadata": {},
  "project_id": "0190...",
  "created_at": "2026-10-25T10:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null
}

Creating a link is free. The console lists your links under Emails, then Authorization links, and can copy the URL again at any time.

Branding

Section titled “Branding”

The page shows a name, logo, description and accent colour. Set defaults once for the project in the console under Branding, with a live preview. A link’s own branding overrides the project’s field by field: send only the fields you want to change. With no branding at all the page is neutral. A small “Powered by clearance.rest” note stays in the footer.

What the visitor sees

Section titled “What the visitor sees”
  1. They open the link and see your branding, in the link’s language, with a button per allowed provider.
  2. They continue to Google or Microsoft, review the permissions and approve.
  3. They return to a result page that shows the connected address, with a button back to return_url if you set one. If they declined, or the mailbox is already connected elsewhere, the page explains what happened and offers to try again while the link is still usable.

A link that expired, was revoked or reached max_uses shows that instead. Starting from it through the API returns 410 auth_link_expired, auth_link_revoked or auth_link_exhausted.

What happens when a mailbox connects

Section titled “What happens when a mailbox connects”

  • The link’s use_count goes up by one, to at most max_uses. A failed connection does not count.

  • The link’s metadata is merged into the mailbox’s own metadata, so you can recognise whose mailbox it is.

  • An email_account.connected webhook event is sent. It carries the mailbox, the auth_link_id and the metadata:

    {
      "type": "email_account.connected",
      "data": {
        "account": { "id": "0190...", "email": "user@gmail.com", "email_provider": "gmail", "metadata": { "customer": "c1" } },
        "auth_link_id": "0190...",
        "metadata": { "customer": "c1" }
      }
    }

Use the event, or GET /emails/auth-links/{id} which lists the mailboxes connected with the link (uses), to find out when someone has connected.

Section titled “Manage links”
Request
GET /emails/auth-links List links. Filter by status: active, expired, revoked, exhausted.
GET /emails/auth-links/{id} One link, with the mailboxes connected through it.
DELETE /emails/auth-links/{id} Revoke it. Mailboxes already connected stay connected.

A link is revoked once revoked, otherwise expired after its expiry, otherwise exhausted once it reached max_uses, and active while none of those applies.