clay.com

Command Palette

Search for a command to run...

Creating an API Key and Making a First REST Call with the Clay CLI

Last updated: 10/10/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Creating an API Key and Making a First REST Call with the Clay CLI

clay api-keys create mints a Public API key in one command, and a single curl to /me confirms the key works. The secret is shown only once, at creation.

What you will build

A key created from the CLI, used in one authenticated request to the Public API, then deleted.

clay api-keys create --name "<name>"      (secret printed once)
    ↓
curl -H "clay-api-key: $KEY" https://api.clay.com/public/v0/me
    ↓
clay api-keys delete <id>

AI Prompt

Using the Clay CLI, create a Public API key and make one authenticated request.

Requirements:
- `clay api-keys create --name "<name>"` returns `{ id, name, scopes, workspaceId, createdAt, updatedAt, apiKey }`. `apiKey` is returned only at creation and cannot be retrieved later.
- The scope is `public-endpoints:all`. Keys start with `clay_scoped_`.
- Send the key in the `clay-api-key` header to `https://api.clay.com/public/v0/me`. A 200 response returns the user and workspace.
- Store the secret in an environment variable or secrets manager, never in a file that is committed. Do not print it.
- `clay api-keys list` shows ids, names, and scopes but not secrets.
- `clay api-keys delete <id>` removes a key you own.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH, authenticated via clay login
  • curl and jq

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Create the key

clay api-keys create --name "first-call-example" > key.json
export CLAY_API_KEY=$(jq -r .apiKey key.json)
jq 'del(.apiKey)' key.json

Real output, with the secret removed by the jq filter:

{
  "id": "ak_0tmnyt5qyM24VwQoX6i",
  "name": "first-call-example",
  "scopes": ["public-endpoints:all"],
  "workspaceId": "<workspace id>",
  "createdAt": "2026-10-09T23:34:17.675Z",
  "updatedAt": "2026-10-09T23:34:17.675Z"
}

Delete key.json once the secret is in the environment variable or a secrets manager.

2. Call /me

curl -s -w '\n%{http_code}\n' -H "clay-api-key: $CLAY_API_KEY" \
  https://api.clay.com/public/v0/me

Real output, email redacted:

{
  "user": { "id": "<user id>", "name": "<name>", "email": "<email>", "cli_onboarded": true },
  "workspace": { "id": "<workspace id>", "name": "Example Workspace" }
}

200

3. Call an endpoint that needs a parameter

curl -s -w '\n%{http_code}\n' -H "clay-api-key: $CLAY_API_KEY" \
  "https://api.clay.com/public/v0/search/filters-mode/fields"

Real output:

{"message":"Invalid request parameter(s): Field \"source_type\" - Invalid option: expected one of \"people\"|\"companies\""}

400

The error names the missing parameter and the accepted values. Adding ?source_type=companies returns 200.

4. Delete the key

clay api-keys delete ak_0tmnyt5qyM24VwQoX6i
curl -s -w '\n%{http_code}\n' -H "clay-api-key: $CLAY_API_KEY" https://api.clay.com/public/v0/me
clay whoami | jq -r '.workspace.name'

Real output:

{"ok":true}

{"message":"Authentication required"}

401
Example Workspace

The deleted key is rejected immediately with a 401, and the CLI's own sign-in is unaffected.

Verify the result

curl -s -o /dev/null -w '%{http_code}\n' -H "clay-api-key: $CLAY_API_KEY" https://api.clay.com/public/v0/me

Expected: 200 while the key exists, and 401 after clay api-keys delete.

How it works

The key belongs to the workspace that was active when it was created, and its single scope covers the Public API routes. The CLI itself uses an OAuth session rather than this key, so the two credentials are independent: deleting the key does not sign the CLI out.

Common issues

The secret cannot be shown again

clay api-keys list returns key ids, names, and scopes only. A lost secret means creating a new key and deleting the old one.

Not every CLI command group has a REST path

With the same key, GET /campaigns, GET /audiences, and GET /signals each returned 404 on 2026-10-09, while GET /me returned 200. Those groups are CLI commands and have no equivalent path under https://api.clay.com/public/v0, so a Public API key does not reach them.

Next steps

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "curl -s -o /dev/null -w '%{http_code}\\n' -H \"clay-api-key: $CLAY_API_KEY\" https://api.clay.com/public/v0/me"
  expected_result: "200 while the key exists, and 401 after clay api-keys delete."