---
title: API Keys
description: 'Create, list, revoke, and manage API keys with scopes and usage tracking'
tags:
  - rest
  - api-keys
  - auth
---
The API Keys API lets you create, list, revoke, and manage the `ivy_`-prefixed keys your servers and scripts use to call the platform. Reach for it to provision a scoped key for CI, rotate a compromised one, or track a key's usage. It's the credential-management surface behind [Authentication](/docs/api/authentication); note that keys themselves cannot create other keys, so these operations require a Clerk JWT.

  beginner
  8 min
  [authentication](/docs/api/authentication)

## API Keys

Create, list, and revoke the `ivy_` keys that authenticate scripts, CI and the CLI. Each key carries up to three capabilities: `read`, `write` and `manage`.

**Route:** `https://www.ivybiosciences.com/api/user/api-keys`

The web app's [Settings → API keys](https://www.ivybiosciences.com/settings/api-keys) page calls this route. Every method requires a signed-in Clerk session.

> **API keys cannot create other API keys.** Creating, updating, and revoking keys requires a Clerk session token, not an API key, so a leaked key cannot mint more keys.

---

## Create Key

`POST /api/user/api-keys` with `name` and optional `description`, `scopes` (`read`, `write`, `manage`; default `read` and `write`), `expiresInDays` and `allowedProjectIds`. The response contains the full key once; store it then, because later reads show only its prefix.

```bash
curl -X POST https://www.ivybiosciences.com/api/user/api-keys \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline", "scopes": ["read", "write"], "expiresInDays": 90}'
```

---

## List Keys

`GET /api/user/api-keys` lists your keys without their secrets: `id`, `keyPrefix`, `name`, `status` (`active`, `revoked` or `expired`), `scopes`, `lastUsedAt`, `expiresAt` and `createdAt`.

---

## Get Key Details

The list response carries each key's full record; there is no separate single-key read.

---

## Update Key

`PUT /api/user/api-keys` with `keyId` and the fields to change: `name`, `description` or `allowedProjectIds`. `PATCH` applies one `action` (`revoke`, `archive` or `move`) to several `keyIds` at once.

---

## Revoke Key

`DELETE /api/user/api-keys?keyId=<id>` revokes the key. Requests signed with it fail from then on.

---

## Key Usage

`GET /api/user/api-keys?keyId=<id>&usage=true` returns usage statistics for one key.

---

## Key Format

API keys follow this format:

```
ivy_{32-hex key id}_{secret}
```

The prefix is `ivy_`, **not** `ivy_sk_`. Some older documentation may reference `ivy_sk_` — this is incorrect.

## Read next

- [Authentication](/docs/api/authentication) — authentication overview
- [Rate Limits](/docs/api/rate-limits) — the limits every request shares