API keys

Authentication

Every request must be authenticated with an API key issued for your brand. Supply the key in the x-api-key request header. A request without a valid key returns INVALID_API_KEY.

Getting a key

Open API keys in the dashboard and sign in.
Pick the brand the key is for. A key is issued per brand and reaches that brand plus every brand linked to it.
Create the key and copy it. It is shown once, so put it somewhere your deployment can read before you close the dialog.

An owner or an admin can issue one. If you only need to try a call, the sandbox answers with a public key and no sign-in.

Python

from zelf import ZelfAPIClient

client = ZelfAPIClient(api_key="<your-api-key>")

The header

The key travels in x-api-key and nowhere else. There is no query parameter for it, so a key never reaches a URL, a browser history or an access log.

All responses are returned as application/json; the Accept header is not required.

The environment

Every client falls back to these two when nothing is passed to it, so a deployed service holds no key in its code.

ZELF_API_KEY: The key the client sends as x-api-key.
ZELF_BASE_URL: The origin to call. It defaults to https://api.hellozelf.com.

Without a valid key

The request is refused before it reaches the resource, with a 401 and one of these codes.

INVALID_API_KEY: The x-api-key header is missing, malformed, or doesn't match a known key.
EXPIRED_API_KEY: The key was valid but its expiration date has passed. Issue a new key.
REVOKED_API_KEY: The key was explicitly revoked. Issue a new key.

Every code the API returns is on the Errors page.