Skip to content
EntryWick documentation

For a developer connecting their own system, Zapier or a script to an organization's EntryWick data.

API keys — api.entrywick.io/v1

Who uses it: a developer connecting their own system, Zapier or a script to an organization's EntryWick data.

What they came to do: get a key that can read (and, on Scale, change) what the organization's admins can, and know the limits before they hit them.

True when they leave: GET /v1/me answers with their organization, the key's scopes, what the plan allows and the organization's own words for things.

Getting a key

An organizer with tenant.api_keys (Owner, Admin or Developer) opens Organization → API keys and makes one. The key is shown once; EntryWick keeps only a hash. Choose:

  • Mode — Live, or Test (ewk_test_…, for building and rehearsing; see scanner-api.md for what test check-ins do).
  • Scopes — read (GET), write (create, change and act), admin, scanner. Scopes are exact: a key that reads and writes needs both ticked, and admin does not stand in for either.
  • Part of the organization — a key limited to a group sees and changes only that group's subtree, exactly as a member limited to that group does.
  • Expiry, IP addresses or ranges, and requests per minute (60 unless set).

Calling the API

curl https://api.entrywick.io/v1/me -H "Authorization: Bearer ewk_live_…"

The key names the organization, so there is no organization in the address. Every POST needs an Idempotency-Key header; a retry with the same key and body gets the first answer back for 24 hours. Every change is recorded in the audit log with the key as the actor and api as the source.

Limits

What Where it comes from When it is reached
Reading (GET) api_read — Growth and above 403 entitlement_required
Changing anything api_write — Scale and above 403 entitlement_required
Requests per minute the key's own rate, never above the plan's api_rate_per_min (Growth 120, Scale 600); one budget per key 429 rate_limited with Retry-After; every answer carries X-RateLimit-Limit and X-RateLimit-Remaining
Calls per month api_calls_monthly (Growth 100,000, Scale 1,000,000); scanner keys count too, paired EntryWick scanners do not Owners are emailed at 80 % and 100 %; nothing stops. Past 150 % calls are refused with 429 quota_exceeded until the 1st of the month (UTC).

The API keys page shows this month's calls against the allowance.

Refusals

Status Code Meaning
401 api_key_required No Authorization: Bearer header
401 api_key_unknown / api_key_revoked / api_key_expired The key cannot be used
403 api_key_ip_not_allowed The key is limited to other addresses
403 api_key_scope The key lacks the scope this call needs
403 entitlement_required The plan does not include this part of the API; error.key and error.upgrade_plan say which
403 instance_read_only Self-hosted only: the license was revoked and its seven days are over, so the API takes reads and exports but no writes; error.read_only_since says when (license states)
422 license_not_valid Self-hosted only, publishing an event: the license key is expired, missing or does not verify; error.validity says which
429 rate_limited / quota_exceeded Too fast / the month's calls are used up

Every error has the same shape: {"error": {"code", "message", "details"?, "request_id"}}.