Envoy CRM
Sign inSign up

Authentication

Guide

Every request is authenticated with a single bearer token - Authorization: Bearer envoy_live_.... There's no separate org identifier to send: the key itself identifies both who's calling and which organisation the request is for.

Keys belong to a person, not just the org

Each key is created by, and attributed to, one member of your organisation - like a GitHub personal access token, not a bare shared secret. A key created by an admin has full access to the organisation's data, the same as that admin has in the app. A key created by a standard member who's restricted to specific brands inherits exactly those restrictions - it can only see and write data for the brands its creator has access to.

This stays live: if a key's creator is promoted, demoted, or granted access to another brand, the key reflects that on its very next call.

Read-only keys

Any key can be marked read-only when it's created. A read-only key can make GET requests but any write (POST, PATCH, DELETE) is rejected with 403. Use this for integrations that only ever need to pull data out.

Expiry and revocation

A key can optionally be given an expiry date when it's created. Any key can be revoked at any time from Settings → API keys - by the person who created it, or by an admin. Revocation takes effect immediately; there's no cache or delay to wait out.

If a key's creator leaves the organisation

Removing someone from your organisation doesn't automatically break integrations they set up, but it also can't be allowed to silently grant a brand-restricted key full access it never had. Envoy resolves this by what the creator's role was at the moment the key was created:

  • A key created by an admin keeps working at full access once its creator is removed - the same access it always had.
  • A key created by a brand-restricted standard member stops working once its creator is removed. Have an admin create a replacement.

Keeping keys safe

A key is shown in full exactly once, at creation - only a hash is stored, so it can never be displayed again if you lose it (revoke it and create a new one instead). Treat a key like a password: never commit it to a repository, and never call the API directly from code that runs in a browser - a key embedded in frontend JavaScript is a key embedded in every visitor's developer tools. Testing a request from this site's API reference page is fine (you're pasting your own key into your own browser, once, deliberately) - shipping that same pattern in your own product isn't.

Next