API tokens

API tokens let an external tool read your account's data over the Reach REST API without signing in as a person. You create each token on the API tokens settings page, choose which scopes it grants, copy the secret once, and revoke it whenever you want to cut off access. Every token is read-only and scoped to a single account.

Who can create tokens

The API tokens page lives under account settings, and only an account owner or admin can open it. If your role is anything else, the settings section shows an admin-access notice instead of the page, so a token has to come from someone with that role.

Creating a token

Open API tokens in Settings and fill in the Create a token card:

• Name: a label so you can tell tokens apart later (for example Zapier production). Required.
• Scopes: the data the token may read. At least one scope is required; the form pre-checks contacts:read. The available scopes are listed in the next section.
• Expires at: an optional date and time after which the token stops working. Leave it blank for a token that never expires on its own.

Click Create token. If you submit with no scope selected, the form blocks the request with "Select at least one scope." On success a Token created dialog shows the full secret, which begins with mrl_. Use Copy to put it on your clipboard, then close the dialog with I've saved it.

What each scope grants

Scopes are read-only and are checked on every request, so a token reads only what its scopes allow. The create form offers four scopes:

• Read contacts (contacts:read): lists and reads contacts.
• Read companies (companies:read): lists and reads companies (organizations).
• Read lists (lists:read): reads your contact lists and the contacts in a list.
• Read deals (deals:read): reserved. You can grant the scope, but the deals endpoint is not yet implemented and returns a 501 for now.

Two more scopes, objects:read and records:read, exist and gate live endpoints for custom object types and their records, but this form does not offer them. There is currently no way to create a token that can call those endpoints. See API reference for what those endpoints return once that gap closes.

Using a token with the API

Send the token as a bearer credential in the Authorization header on every request: Authorization: Bearer mrl_<your-token>. For the full endpoint list, request and response shapes, rate limits, and error codes, see API reference.

Reviewing and revoking tokens

The Existing tokens table lists every token for your account, newest first, with these columns:

• Name: the label you gave the token.
• Prefix: the first eight characters after mrl_, shown as mrl_xxxxxxxx…. Use it to match a row to a token without exposing the full secret.
• Scopes: the scopes granted at creation. Scopes are fixed once the token is created.
• Last used: the time of the most recent successful API call, or "Never" if the token has not been used.
• Status: Active, Expired (once its Expires at time has passed), or Revoked.

To revoke a token, click the trash icon on its row. A confirmation prompt asks "Revoke token '<name>'? Any clients using it will get 401 immediately. This cannot be undone." Confirm to revoke. Once revoked, the row's status changes to Revoked and the trash icon disappears. An expired token does not need revoking; you can leave it or revoke it to be explicit.