Authentication & API credentials

The Itefy API uses API keys — long-lived bearer tokens, scoped to a single account.

Create an API key

1. Open the web app and go to Settings → API keys.

2. Click Create key and give it a descriptive name (e.g. "Warehouse sync").

3. Choose the key's access: Full access (everything the creating user can do) or Restricted — pick per resource whether the key may read or read + write (see Scopes below).

4. Copy the generated token immediately — it is shown only once:

   itf_live_<id>_<secret>

5. Store it somewhere secure (a secrets manager / environment variable). Itefy only keeps a hash of the secret, so it cannot show it to you again. If you lose it, revoke the key and create a new one.

Settings → API keys.

Plan requirement

External API keys are available on Business and Enterprise plans (Business allows 5 keys, Enterprise 25). On other plans the API keys page shows an upgrade prompt instead.

Trying the API on a trial: during a free trial you can create one API key to evaluate the integration. When the trial ends the key stops working until you subscribe to a plan with API access.

Authenticate a request

Send the token as a Bearer credential in the Authorization header:

Authorization: Bearer itf_live_<id>_<secret>

The key is bound to one account, so you don't need to specify the account separately — and every record your integration creates is attributed to the key's own identity, shown as "⟨key name⟩ (API)" (e.g. "Warehouse sync (API)"), so API activity is always distinguishable from what people did by hand. The key's identity does not count toward your plan's user seats. You can also set an optional contact email on the key, where Itefy can send operational notices about the integration.

curl -H "Authorization: Bearer itf_live_<id>_<secret>" \
  https://api.itefy.com/v1/whoami

A missing or invalid key returns 401 with error.code = invalid_api_key.

Scopes

A key created with Restricted access carries a list of scopes of the form <resource>:read or <resource>:write, per resource: items, locations, contacts, users (read-only), reservations, checkouts, events, issues, comments.

• Write includes read — a key with items:write can also list and fetch items.
• A key created with Full access has no scope list and can use every endpoint its creating user can.
• Calling an endpoint outside the key's scopes returns 403 with error.code = insufficient_scope.
• Scopes can be changed at any time in Settings → API keys → Edit access. Changes apply immediately to every request made with the key.
• Scopes can only narrow access: every key is additionally bounded by its creating user's permissions in the account.

Which endpoints each scope covers

Scope	Grants access to
items:read	GET /v1/items, GET /v1/items/lookup, GET /v1/items/{id}, GET /v1/items/{id}/pictures
items:write	everything in items:read, plus POST /v1/items, PATCH /v1/items/{id}, DELETE /v1/items/{id}, POST /v1/items/{id}/condition, POST /v1/items/{id}/location, POST /v1/items/{id}/inventory, POST /v1/items/{id}/files
locations:read	GET /v1/locations, GET /v1/locations/{id}
locations:write	reads, plus POST /v1/locations, PATCH /v1/locations/{id}, DELETE /v1/locations/{id}
contacts:read	GET /v1/contacts, GET /v1/contacts/{id}
contacts:write	reads, plus POST /v1/contacts, PATCH /v1/contacts/{id}, DELETE /v1/contacts/{id}
users:read	GET /v1/directory/users, GET /v1/users, GET /v1/users/{id} (read-only — the API has no user-write endpoints)
reservations:read	GET /v1/reservations, GET /v1/reservations/{id}
reservations:write	reads, plus POST /v1/reservations, PATCH /v1/reservations/{id}, POST /v1/reservations/{id}/complete, DELETE /v1/reservations/{id}
checkouts:read	GET /v1/checkouts, GET /v1/checkouts/{id}
checkouts:write	reads, plus POST /v1/checkouts, POST /v1/checkouts/{id}/checkin
events:read	GET /v1/events, GET /v1/events/{id}
events:write	reads, plus POST /v1/events, DELETE /v1/events/{id}
issues:read	GET /v1/issues, GET /v1/issues/{id}
issues:write	reads, plus POST /v1/issues, PATCH /v1/issues/{id}, POST /v1/issues/{id}/status, DELETE /v1/issues/{id}
comments:read	GET /v1/comments
comments:write	reads, plus POST /v1/comments, DELETE /v1/comments/{id}

GET /v1/ping, GET /v1/whoami and the OpenAPI document need no scope — every valid key can call them (handy for health checks and verifying a key's identity).

How scopes and user permissions combine

A request made with an API key must pass all of these checks, in order:

1. Plan — the account has API access (Business/Enterprise, or an active trial).
2. Scope — the endpoint is covered by the key's scopes (table above). Full-access keys skip this check. Failing returns 403 insufficient_scope.
3. User permission — the endpoint's permission category is granted to the key's creating user (for example, item endpoints require the Items content permission, checkout endpoints the Check-in/check-out action permission, /v1/users the Users administration permission). Failing returns a plain 403.

So a key can never do more than the person who created it — scopes only narrow further.

Personal endpoints (/v1/notifications, /v1/push/…) and the first-party bootstrap endpoints (/v1/auth/…, /v1/accounts, /v1/session) belong to Itefy's own apps and are not available to API keys at all — they return 403 with error.code = first_party_only.

Rate limits

API-key traffic is limited to 300 requests per minute per key. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers; exceeding the limit returns 429 Too Many Requests. Back off and retry after the reset.

Revoke a key

In Settings → API keys, click Revoke next to a key. Revocation is immediate and permanent — any integration using that token will start receiving 401. Revoke keys that are unused or may have been exposed.

Next steps

• Usage examples — ready-to-run curl calls
• API reference — every endpoint, interactively