Skip to main content
Every route except GET /health and GET /openapi.json needs an API key. Send the key in the Authorization header:

​
Getting a key

Create keys under Settings → API keys, and choose what each key can read and write. The secret is shown once, when the key is created. Store it in a secrets manager, not in source control. There are two kinds of key:
  • A personal key belongs to you, for your own scripts and agents. Anyone in your Synthetic account can create one. It acts as you, so it can never do more than you can. If your access is narrowed, your keys are narrowed with it, and if you leave the account they stop working.
  • An organization key belongs to the business, for integrations that must keep working when people leave. Only an administrator can create one.

​
What a key can do

  • A key reads and writes the data of one business, the one it was created for. Data belonging to anyone else is not found.
  • Each route needs a claim, such as payments:read to read payments or customers:write to write customers. A key given write access also holds the read claim, and payments can only be read.
  • A key holds the claims chosen when it was created, and they cannot be changed afterwards. GET /me shows the key as apiKey, and what it may do now as authorizationClaims.
  • A business can have up to ten active organization keys, and each person up to ten active personal keys.

​
Renaming and revoking a key

You rename or revoke your own keys from the same Settings → API keys page. An administrator can rename or revoke any key, including another person’s. Revocation takes effect immediately, and every request with that key is refused from then on. A request with a missing, unknown or revoked key returns 401. See Errors.