1. Help Center
  2. Developer Tools

Create and Use API Keys

API keys let your own apps, scripts, and integrations talk to your workspace programmatically. Each key carries a set of scopes that decide exactly what it's allowed to do, so you can hand out narrow access instead of your full account.

You'll find them under Developer tools in your account menu — the avatar at the corner of your workspace.

How keys and tokens fit together

A key has two parts:

  • Key ID — a public identifier, e.g. wlk_…. It's safe to store in config.
  • Secret — the private half, e.g. wsk_…. Treat it like a password.

You don't send the key and secret on every request. Instead you exchange them once for a short-lived access token plus a refresh token, and use those to make calls. When the access token expires, the refresh token gets you a new pair — no need to re-send the secret.

Create a key

  1. Open Developer tools and choose Create API key.
  2. Give it a name you'll recognise later, e.g. "Zapier" or "Reporting script".
  3. Pick the scopes it needs. Grant only what the integration actually uses — for a read-only export, read scopes are enough.
  4. Optionally set an expiration. An expiring key is safer for temporary work.
  5. Choose Create key.

The secret is shown only once, right after creation. Copy it and store it somewhere safe — a password manager or your app's secret store. If you lose it, you can't recover it; revoke the key and create a new one.

Get an access token

Exchange the key ID and secret for a token pair:

curl -X POST https://api.waitlist.co.il/identity-provider/v1/api-keys/token \
  -H 'Content-Type: application/json' \
  -d '{ "keyId": "wlk_…", "secret": "wsk_…" }'

The response contains an accessToken, a refreshToken, and the scopes granted. Send the access token as a bearer token on your API calls:

Authorization: Bearer <accessToken>

When the access token expires, rotate it with the refresh token:

curl -X POST https://api.waitlist.co.il/identity-provider/v1/api-keys/token/refresh \
  -H 'Content-Type: application/json' \
  -d '{ "refreshToken": "<refreshToken>" }'

Each refresh returns a new refresh token and invalidates the old one, so always store the latest.

Scopes

A scope is a resource:action pair — for example clients:read or clients:create. Actions are read, create, update, and delete. Two shorthands are supported:

  • resource:* grants every action on a resource, e.g. clients:*.
  • * grants everything (the "select all" option).

The scopes you can grant are limited to what your own role already allows, so a key can never do more than you can. Pick the smallest set that gets the job done — you can't change a key's scopes after creation, so create a new key if the needs change.

Revoke a key

If a key is no longer needed, or a secret might have leaked, open Developer tools and choose Revoke on that key. Revoking is immediate: existing tokens stop working and can no longer be refreshed. This can't be undone, so revoke and re-create rather than reusing a compromised key.

Keep keys safe

  • Never commit a secret to source control or paste it into a shared document.
  • Store secrets in a password manager or your platform's secret store.
  • Use a separate key per integration so you can revoke one without disrupting the others.
  • Prefer expiring keys for temporary or third-party access.
Create and Use API Keys | waitlist