# Authentication

Every Clikso API request carries a workspace API key as a Bearer token. Learn how to make a key, what Read, Write and Admin allow, and how keys stay safe.

> **In short:**
>
> Every request sends an API key in the `Authorization` header, as `Bearer clik_live_…`. A key belongs to one workspace. It acts as the person who made it, and it can never do more than that person can.

## You need

* **A plan:** Any plan. The API works on Free too.
* **A role:** Admin in the workspace. Only admins can create, rename, revoke or delete keys.
* **A safe place:** Somewhere to keep the key, such as an environment variable or a secrets manager.

## Create a key

### Step 1. Open the API settings

Sign in at [app.clik.so](https://app.clik.so). Open **Settings**, then the **API** tab. Press **Generate New Key**.

### Step 2. Name the key and pick its permission

Give the key a name of up to 30 characters, such as "Order emails". The name helps you spot it later.

Then tick a permission. **Write** also gives **Read**, and **Admin** gives both. Press **Generate Key**.

### Step 3. Copy the key once

The **Save your API key** window shows the full key. This is the only time you will see it. Copy it now and store it safely.

A key looks like `clik_live_` followed by 32 letters and digits.

## Send the key

Put the key in the `Authorization` header of every request, after the word `Bearer` and a space.

```http title="Header"
Authorization: Bearer clik_live_your_key_here
```

The `X-API-Key` header does not work. Only `Authorization: Bearer` does.

## Check your key

This call reads your workspace's usage. Any key with Read permission can make it, so it is a good first test.

```bash
curl "https://app.clik.so/api/workspace/usage" \
  -H "Authorization: Bearer $CLIKSO_API_KEY"
```

Response 200:

```json
{
  "status": 200,
  "success": true,
  "message": "Success",
  "data": {
    "workspace_id": "8a1f2c3d-4b5e-4f60-9a7b-1c2d3e4f5a6b",
    "links_created_this_month": 42,
    "clicks_this_month": 1873,
    "ai_analytics_today": 0,
    "ai_slug_gens_today": 3,
    "last_reset_ai": "2026-10-09",
    "last_reset_monthly": "2026-10-01",
    "next_reset": "2026-11-01T00:00:00.000Z",
    "updated_at": "2026-10-09T09:30:00.000Z",
    "plan_key": "starter",
    "plan_links_limit": 500,
    "plan_domains_limit": 2,
    "is_simulated": false
  }
}
```

A `200` means the key works. A `401` means the key is wrong, revoked or missing.

## What each permission allows

A key's permission sets the most it can do. Your own role in the workspace also counts. The key gets whichever of the two is lower.

* **Read** acts like a viewer. It can read links, folders, tags, domains, usage and click analytics.
* **Write** acts like an editor. It can do everything Read can, and also create, change and delete links, folders and tags.
* **Admin** is the same as Write for now. No API route needs more than Write today.

So an editor's Admin key still acts as an editor. And an admin's Read key can only read.

## What keys can never do

Some parts of Clikso stay in the dashboard. A key that calls them gets `403 API_KEY_NOT_ALLOWED`, whatever its permission.

* Create, list or revoke API keys.
* Change billing, members, invitations or workspace settings.
* Add, verify or delete custom domains. Keys can only read them.
* Reveal a link's password.
* Upload a social preview image, or use the AI analytics chat.

This keeps a leaked key from taking over your account.

## One key, one workspace

Each key belongs to the workspace you made it in. Every link it creates lands there. To work with two workspaces, make one key in each.

You can also send a `Workspace-Id` header with the workspace id. You do not have to. But if you send it, it must match the key's workspace, or you get `403 FORBIDDEN`. That stops a script from writing to the wrong place by mistake.

## When people change

A key follows its creator, live, on every request.

* If the creator becomes a viewer, their Write key can only read.
* If the creator leaves the workspace, their keys stop working with `403 FORBIDDEN`.
* If the creator's account is suspended, every call gets `403 ACCOUNT_BANNED`.
* If the creator has not verified their email address, calls can get `403 EMAIL_NOT_VERIFIED`.

To keep a script running when people change, have an admin who stays make its key.

## What you get back

When the key is fine, you get the normal response for that endpoint. When it is not, you get an error with a `code` that tells you why. Every error has the same shape. See [Requests and responses](https://clik.so/docs/requests#response-envelope).

## Common errors

| Status | Code                  | What it means                                                                      | What to do                                                                                               |
| ------ | --------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 401    | `UNAUTHORIZED`        | The header is missing, or the key is mistyped, deleted or unknown.                 | Send `Authorization: Bearer clik_live_…` with a key from Settings → API.                                 |
| 401    | `API_KEY_REVOKED`     | Someone revoked the key in **Settings → API**.                                     | Create a new key and replace the old one.                                                                |
| 401    | `API_KEY_EXPIRED`     | The key had an expiry date, and it has passed.                                     | Create a new key.                                                                                        |
| 403    | `FORBIDDEN`           | The permission or role is too low, or `Workspace-Id` names another workspace.      | Check the key’s permission and your role. If you send `Workspace-Id`, it must match the key’s workspace. |
| 403    | `API_KEY_NOT_ALLOWED` | This endpoint never accepts API keys.                                              | Use only the endpoints in the API reference.                                                             |
| 403    | `EMAIL_NOT_VERIFIED`  | The person who made the key has not verified their email.                          | Sign in to the dashboard and verify the email.                                                           |
| 429    | `RATE_LIMITED`        | Too many requests this minute, or too many failed key checks from your IP address. | Wait the number of seconds in the `Retry-After` header, then try again.                                  |

## Good to know

* Your workspace can hold 3 keys on Free, 10 on Starter, 20 on Pro and 30 on Business. Revoked keys do not count; each browser connected to the Clikso extension holds one that does.
* The key limit only applies when you create a key. If you move to a smaller plan, the keys you have keep working.
* Each key has its own request limit per minute. See [Limits](https://clik.so/docs/limits).
* One IP address can fail 30 key checks a minute. Past that, its failed checks get `429 RATE_LIMITED` until the minute ends.
* To change a key, make a new one, switch your code to it, then revoke the old one.
* Keep keys out of web pages, apps and Git. See [Keep your API key safe](https://clik.so/docs/guides/api-key-safety).

---

Source: https://clik.so/docs/authentication