---
title: API Token
kind: resource
slug: api-token
summary: "A legacy CLI/MCP bearer token (`drop_…`). Shown only once at creation. New auth uses Cognito SSO; tokens remain for backwards compatibility."
---

# API Token

A legacy CLI/MCP bearer token (`drop_…`). Shown only once at creation. New auth uses Cognito SSO; tokens remain for backwards compatibility.

An **API Token** is a long-lived bearer credential for the CLI and MCP server. Tokens are prefixed `drop_` and stored only as a SHA-256 hash — the plaintext is shown **exactly once** at creation. Today, `drop login` provisions Cognito JWTs via OAuth + PKCE (auto-refreshing in `~/.drop/credentials.json`); API tokens are the **legacy** path, accepted alongside JWTs until the `LEGACY_TOKEN_CUTOFF_DATE`. Prefer `drop login` for new setups.

## The API Token object

### Attributes

- **`name`** `string` — Owner-facing label for the token (e.g. "CLI Token", "CI deploy token"). Default `"CLI Token"`. Helps identify which token to revoke when you no longer need it.
- **`lastUsed`** `timestamp · nullable` — Updated on every successful auth. Useful for spotting unused tokens to revoke. `null` until the token is used for the first time.
- **`expiresAt`** `timestamp · nullable` — When the token stops being accepted. Newly-issued tokens default to **1 year** from creation. Past expiry, the token returns 401 from every endpoint.
- **`userId`** `string` — The owning User. Every request authenticated by this token acts as that User — there is no scoping below the user level.
- **`createdAt`** `timestamp` — ISO 8601 timestamp of creation.
- **`id`** `string · less-common` — CUID primary key. Pass this as `tokenId` when revoking via [Revoke](#delete).
- **`tokenHash`** `string · less-common` — SHA-256 hash of the raw token. Never returned by the API — the plaintext is shown exactly once at creation and must be stored securely by the caller.

### JSON example

```json
{
  "id": "clxtok1...",
  "userId": "usr_alex",
  "name": "CI deploy token",
  "lastUsed": "2026-06-02T08:42:00.000Z",
  "expiresAt": "2027-06-01T00:00:00.000Z",
  "createdAt": "2026-06-01T00:00:00.000Z"
}
```

## Methods

### List tokens

`GET /api/tokens`

List your own API tokens. Token hashes and raw values are never returned — only metadata (`name`, `lastUsed`, `createdAt`). **Session auth only** (the web UI). Token-authenticated callers cannot list other tokens.

**CLI**

```bash
# Not yet in the CLI — manage tokens at /settings in the dashboard.
```

**HTTP**

```bash
curl https://drop.himarley.ai/api/tokens \
  -H "Cookie: next-auth.session-token=..."
```

**Response** (200)

```json
{
  "tokens": [
    {
      "id": "clxtok1...",
      "name": "CI deploy token",
      "lastUsed": "2026-06-02T08:42:00.000Z",
      "createdAt": "2026-06-01T00:00:00.000Z"
    }
  ]
}
```

### Create a token

`POST /api/tokens`

Generate a new API token. The raw token is returned **only once** in the response — store it immediately (a password manager or your CI secret store). Tokens are prefixed `drop_`, hashed at rest, and default to a 1-year expiry. **Session auth only.** For most workflows, prefer `drop login` (which provisions auto-refreshing Cognito JWTs and writes them to `~/.drop/credentials.json`).

**CLI**

```bash
# Not yet in the CLI — create tokens at /settings in the dashboard.
# For everyday use, prefer:
drop login
```

**HTTP**

```bash
curl -X POST https://drop.himarley.ai/api/tokens \
  -H "Cookie: next-auth.session-token=..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI deploy token" }'
```

**Response** (201)

```json
{
  "token": "drop_Abc123Def456Ghi789...",
  "name": "CI deploy token"
}
```

### Revoke a token

`DELETE /api/tokens`

Revoke a token by id. The token stops working immediately for CLI and MCP auth. Use this if a token leaked or a CI environment was decommissioned.

**CLI**

```bash
# Not yet in the CLI — revoke tokens at /settings in the dashboard.
```

**HTTP**

```bash
curl -X DELETE https://drop.himarley.ai/api/tokens \
  -H "Cookie: next-auth.session-token=..." \
  -H "Content-Type: application/json" \
  -d '{ "tokenId": "clxtok1..." }'
```

**Response** (200)

```json
{ "success": true }
```