Authentication

Every request to the Essentio Public API carries a credential: an API key, or the access token of a Connected app. The credential decides which Business the request acts for and what it may do there; no request names a Business.

API keys

Send the key in the Authorization header as a bearer token:

Example request with an API key

curl https://api.essentio.pro/v1/clients \
  -H "Authorization: Bearer ess_your_api_key"

An Owner or Admin creates keys in Essentio under Settings → API Keys. A key:

  • belongs to its Business, not to the person who created it. It keeps working, with the Role it was given, when that person leaves the Business, is given another Role or deletes their account;
  • acts with one Role — Admin, Member or Viewer, never Owner. A request may do what that Role may do in Essentio, and nothing more;
  • is shown once, when it is created. Essentio stores only a fingerprint of it and the first characters it lists the key by;
  • stops working the moment it is revoked.

The API sets no cookie and keeps no session: each request stands alone.

Connected apps

Software that other people's Businesses connect to — your product, or an AI assistant — is an OAuth app. A person connects it to one of their Businesses on Essentio's consent screen, and it then calls the API with an access token, sent the same way as a key:

Example request with an access token

curl https://api.essentio.pro/v1/clients \
  -H "Authorization: Bearer ACCESS_TOKEN"

Unlike a key, a Connected app belongs to the person who connected it: it never does more than they may do now, and it ends when they leave the Business. See OAuth apps.

Errors

A request without a credential, or with one that no longer acts, is answered 401 with an error of type authentication; a credential whose Role may not do what it asked is answered 403 permission. Every error has the same shape — an error object with a type your code branches on and a message for a person:

A request with no key: 401

{
  "error": {
    "type": "authentication",
    "message": "Send a live API key or access token of the business as \"Authorization: Bearer <credential>\"."
  }
}

Every type, and the Refusal codes of a refused Action, are on Errors and Refusal codes.