> ## Documentation Index > Fetch the complete documentation index at: https://docs.usertick.com/llms.txt > Use this file to discover all available pages before exploring further. # Authentication > API keys that belong to your organization, the scopes they carry, expiry, rotation, access changes and usage. Every request carries one credential as a Bearer token. Usertick accepts two kinds of credential: | Credential | Looks like | Who uses it | | - | - | - | | API key | `utk_live_...` | Your own scripts and servers. Keys are created in the dashboard. | | Access token | `uto_...` | An approved app, such as Zapier, acting for the person who connected it. See [OAuth for apps](https://docs.usertick.com/developers/api/oauth.md). | The credential determines the organization, so no route contains an organization id. ## Send the credential The credential goes in the `Authorization` header. If a client can't set that header, it can send the key in `X-Api-Key` instead. When both headers are present, `Authorization` takes precedence. ```bash Authorization header theme={null} curl "https://app.usertick.com/api/public/v1/me" \ -H "Authorization: Bearer utk_live_your_key_here" ``` ```bash X-Api-Key header theme={null} curl "https://app.usertick.com/api/public/v1/me" \ -H "X-Api-Key: utk_live_your_key_here" ``` `GET /me` needs no scope, which makes it the simplest way to check a key. It returns the organization, the key's name and scopes, and its rate limits. ## Keys belong to the organization An API key belongs to your organization instead of the person who created it. The key keeps working when that person leaves the organization or changes role, and the key list still shows who created each key. A key acts as the organization itself: * Changes it makes appear in the activity log as **via API key** followed by the key's name. * A note it writes shows the key's name as its author. * It can do what its scopes allow, in its own organization only. A key stops working when it is revoked or expires, when the organization is inactive, or when the plan no longer includes the API. In that last case, calls return `403` with `APK-004-005`, and the key works again after an upgrade. > [!WARNING] > > Treat keys like passwords. Keep them in server side configuration, never in browser code or a repository. If a key leaks, revoke it or rotate it. ## Create a key Managing keys requires the **Manage developer settings** permission. Creating or rotating a key also requires the Pro plan or above. **1. Open the form** Under **Settings → Developers → API keys**, select **Create API key**. **2. Name the key** In **Name**, enter what will use the key, such as "CI export job". **3. Select its access** Under **Access**, select only the access the key needs. **4. Choose the expiry** Under **Expires**, select **No expiry**, **In 30 days**, **In 90 days**, **In 1 year** or **On a date**. **5. Copy the key** After you select **Create API key**, copy the key into your secret store before you select **I saved it**. When one kind of access depends on another, the form selects both. A date under **On a date** can be up to 2 years ahead, and the key works through the end of that day in UTC. The full key is shown only once. Usertick stores only a hash of it, so afterward the dashboard shows only the key's prefix. ## Scopes Each scope has a label in the dashboard, shown under **Access**. | Scope | Label | Allows | | - | - | - | | `surveys:read` | Read surveys | Listing surveys, reading a survey and its questions, listing sites | | `surveys:write` | Pause and resume surveys | Pausing and resuming surveys | | `responses:read` | Read responses | Reading responses, their notes and files, and the analysis tree | | `responses:write` | Update responses | Changing a response's status, type, urgency and assignees, writing notes, listing members | | `responses:delete` | Delete responses | Erasing responses, one at a time or everything one person sent, and following those jobs | | `analytics:read` | Read metrics | Reading metrics: counts, scores, time series and breakdowns | | `webhooks:read` | Read webhooks | Listing the credential's own webhook subscriptions and their deliveries | | `webhooks:write` | Manage webhooks | Subscribing and unsubscribing URLs, resending deliveries, and listing workflow Zapier steps | Three endpoints also need `responses:read`. The first two return response data, and the third lists what a subscription can receive: | Endpoint | Scopes | | - | - | | `PATCH /responses/{responseId}` | `responses:write` and `responses:read` | | `POST /webhooks/subscribe` | `webhooks:write` and `responses:read` | | `GET /workflows/zapier-steps` | `webhooks:write` and `responses:read` | A call without every scope it needs returns `403` with `APK-004-004`. Each page in the API reference lists the scopes of its endpoint. ## Key status | Status | Meaning | | - | - | | **Active** | The key works. | | **Rotating** | The key has a new secret, and the old secret works until its 24 hours are up. | | **Expired** | The expiry date passed, and the key no longer works. | | **Revoked** | Someone revoked the key, and it no longer works. | The key list opens with the **Status** filter set to **Active**, which also shows rotating keys. Revoked and expired keys stay in the list, so their history remains readable: to see them, open **Filters** and pick **Revoked** or **Expired**, or remove the filter. ## Rotate a key To rotate a key, select its row in the key list, select **Rotate key** and then **Rotate now**. Usertick shows the new secret once. The old secret keeps working for **24 hours**, so the new one can be deployed without downtime. The key keeps its id, name, access, expiry, usage history and webhook subscriptions. Rotating again within those 24 hours ends the older secret immediately. A revoked or expired key can't be rotated, so a new key has to be created instead. ## Change a key's access To change what a live key can do, select its row in the key list, select **Edit access**, change the selection and select **Save changes**. The key uses the new access from its next request. When the key loses `webhooks:write` or `responses:read`, every webhook subscription it made stops sending, and the panel says so before you save. A revoked or expired key can't be changed. ## Revoke a key To revoke a key, select its row in the key list, select **Revoke key**, type the key's name and confirm. Revoking stops the key immediately, including both secrets during a rotation. Every webhook subscription the key made stops sending. Revoking can't be undone. ## Review a key's usage When you select a key's row in the key list, the row opens and shows what the key did: * **Usage** shows the requests per day over the last 30 days, split into **Successful (2xx)**, **Client errors (4xx)**, **Rate limited (429)** and **Server errors (5xx)**, with the totals for those 30 days above the chart. * **Recent requests** lists the key's latest 5 calls from the last 7 days, newest first, with the time, method, path, status and duration. Request and response bodies are never kept. * **Show all** opens every call of the last 7 days in a panel, newest first. More calls load as you scroll, and **Filters → Status** narrows the list to succeeded or failed calls, client errors, rate limited calls or server errors. When Usertick couldn't count some of your organization's calls in the period, a line under the chart says how many. The numbers in **Usage** can then be lower than the actual use; the calls themselves were answered as usual. A request without a valid key returns `401` and has no key to count toward, so it doesn't appear in a key's usage. ## Apps Apps that act for other people, such as the [Usertick app for Zapier](https://docs.usertick.com/integrations/zapier.md), don't use API keys. The person approves the app in Usertick, and the app receives an access token. Apps work on the Starter plan and above. See [OAuth for apps](https://docs.usertick.com/developers/api/oauth.md). Each connection of the Zapier app appears under **Connections** in **Settings → Integrations → Zapier**, where a member whose role has the **Manage integrations** or **Manage developer settings** permission can select **Revoke access**. ## Error codes | HTTP | Code | Meaning | | - | - | - | | 401 | `APK-004-001` | No credential on the request | | 401 | `APK-004-002` | The credential is unknown, expired or revoked, or the organization is inactive | | 401 | `APK-004-007` | An AI assistant's token sent to the REST API: it works only through the MCP server | | 403 | `APK-004-004` | The credential lacks a scope the endpoint needs | | 403 | `APK-004-005` | The plan does not include the API (Pro and up) | | 403 | `APK-004-008` | An app's organization is on a plan without apps that use the API (Starter and up) | | 403 | `AUTHZ-001-002` | An app's member lacks the permission for this change | A bad credential always returns `401` instead of `403`. Every code is listed on the [errors page](https://docs.usertick.com/developers/api/errors.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.