> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerorank.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Make a key, choose what it can do, and send it with your requests.

Every API request needs a key. A key proves the request is yours and ties it to one workspace. You make keys in the ZeroRank app, then send one with each request.

<Note>
  Only workspace owners and admins can make or remove keys. A key can read your data and spend your plan usage, so it is kept to those roles.
</Note>

## Make a key

<Steps>
  <Step title="Open Workspace settings">
    In ZeroRank, go to **Workspace** settings and find the **API Access** card.
  </Step>

  <Step title="Click New API key">
    Give the key a name you will recognize later, like `Production server`.
  </Step>

  <Step title="Choose what it can do">
    Leave **Allow write access** on for a key that can change data. Turn it off for a read-only key.
  </Step>

  <Step title="Pick when it expires">
    Choose **Never**, **30 days**, **90 days**, or **1 year**. The key stops working after that.
  </Step>

  <Step title="Copy the key">
    Click **Create key** and copy it right away. You will not see the full key again.
  </Step>
</Steps>

<Warning>
  The full key is shown once, at creation. Copy it and keep it somewhere safe, like a password manager. If you lose it, make a new one.
</Warning>

Every key looks like `zr_live_` followed by a long string of letters and numbers.

## What a key can do

Each key carries one or both of these scopes (the things it is allowed to do):

* **read** — every key has this. It can read your data with `GET` requests.
* **write** — needed to create, update, delete, or run anything.

A read-only key is safe to use where you only need to look at data. A `write` request with a read-only key gets a `403` reply.

<Note>
  In the app, the **Allow write access** switch sets this. On gives a `read` + `write` key. Off gives a read-only key.
</Note>

## Send your key

Put the key in the `Authorization` header of each request, after the word `Bearer`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer zr_live_your_key_here" \
    https://api.zerorank.ai/api/v1/prompts
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.zerorank.ai/api/v1/prompts", {
    headers: { Authorization: "Bearer zr_live_your_key_here" },
  })
  const body = await res.json()
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.zerorank.ai/api/v1/prompts",
      headers={"Authorization": "Bearer zr_live_your_key_here"},
  )
  print(res.json())
  ```
</CodeGroup>

<Warning>
  Keep your key secret, like a password. Do not put it in code you share or in a public place. Use a key with only the access it needs.
</Warning>

## See and remove keys

The **API Access** card lists your active keys. For each one you can see its name, scopes, when it was made, and when it was last used.

To turn a key off, click the trash icon and confirm. The key stops working right away. Do this if a key leaks or you no longer need it.

<Note>
  A workspace can have up to 25 active keys at once. Remove an old key to make room for a new one.
</Note>

## When a request is refused

<AccordionGroup>
  <Accordion title="401 — the key is missing or invalid">
    Check that you sent the `Authorization` header and that it starts with `Bearer `. Make sure the key is not removed or expired.
  </Accordion>

  <Accordion title="403 — the key is read-only">
    You tried to change data with a read-only key. Make a new key with **Allow write access** on, or use one you already have.
  </Accordion>

  <Accordion title="402 or 403 — your plan cannot use the API">
    The API needs a paid plan or an active trial. Check your plan on the [billing page](/account/billing). The free tier cannot use the API.
  </Accordion>

  <Accordion title="429 — too many requests">
    You went over your per-minute limit. Wait the seconds shown in the `Retry-After` header, then try again. Higher plans get a higher limit.
  </Accordion>
</AccordionGroup>

Still stuck? Email [support@zerorank.ai](mailto:support@zerorank.ai).

## Keep going

<CardGroup cols={2}>
  <Card title="API overview" icon="code" href="/api/overview">
    The base address, rate limits, and what comes back.
  </Card>

  <Card title="Billing and plans" icon="credit-card" href="/account/billing">
    See which plan you are on and what it includes.
  </Card>
</CardGroup>