Authentication

Every request to the Essentio Public API carries an API key. The key 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.

Errors

Every error the API answers has one shape: an error object with a type your code can branch on and a message for a person.

A request with no key: 401

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

Name
authentication
Type
401
Description
The request carries no API key, an unknown one or a revoked one.
Name
permission
Type
403
Description
The key’s Role may not do this.
Name
not_found
Type
404
Description
No such endpoint or record.
Name
invalid_request
Type
4xx
Description
Any other request the API cannot answer as sent. A 422 names each field, parameter or header at fault in errors, in the words Essentio’s own forms use.
Name
server_error
Type
5xx
Description
A fault on Essentio’s side.
Name
idempotency
Type
422
Description
An Idempotency-Key sent again with another request than the first one under it. Nothing was done. See Retrying a create safely.

A Client with no email: 422

{
  "error": {
    "type": "invalid_request",
    "message": "The email field is required.",
    "errors": {
      "email": ["The email field is required."]
    }
  }
}