View, rename, rotate, and delete the API key you are calling with. A key can only manage
itself: it cannot create keys, list keys, or view or change any other key, and a request that
names another key returns 403 "An API key can only view or change itself. Manage other API
keys in Settings." Create keys, see every key on the account, change a key's scopes, and
reactivate a deleted key in HiringCenter (Settings -> API / Webhooks), as an admin or owner.
Every key has scopes: read for GET requests and write for POST, PATCH, and DELETE (write
includes read). A read-only key gets 403 "Insufficient permissions: this API key is read-only"
on any change to your data, but any key may still view, rename, rotate, or delete itself. Keys
made in Settings start with read and write. Keys created before scopes keep full read and
write.
An API key can call exactly the operations in this reference, and nothing else; every other
route returns 403 "API key authentication is not allowed for this endpoint".
Validate API Key
Checks the API key sent in the Authorization header and returns its metadata. Any active key
can call this; no permission is required. A missing, unknown, or deleted key returns 401.
Returns the same response as GET /auth.
Responses
OK
successboolean · requiredidstring · requiredAPI key ID (the
<keyId>part of anhc_<keyId>.<secret>key).namestring · requiredName given to the key when it was created.
accountIdstring · requiredAccount the key belongs to.
permissionsstring[] · requiredPermissions stored on the key: the scopes
readandwrite, or older names (prospects:read, ...) on keys created before scopes. Older keys may still list akeysscope, which no longer does anything.createdAtinteger · int64 · requiredUnix timestamp in milliseconds
activeboolean · required
accountNamestring | nullAccount name when available.
userIdstring | nullThe user a key is scoped to (keys created by connecting an AI tool through MCP). Every request with the key acts as this user.
nullfor an account-wide key.scopesstring[]What the key may do:
read(GET) andwrite(other methods; includes read). Keys created before scopes are shown with what they keep:readandwrite.Enum values:readwrite
Get API Key
Returns metadata for the API key you are calling with. Any key may view itself, whatever its
scopes.
The keyId must be the key you are calling with; any other key returns 403.
path Parameters
keyIdstring · requiredThe id of the key you are calling with (
idfromGET /auth).Example: 8f4c2a19d7e34b6f
Responses
OK
successboolean · requiredkeyobject · requiredAPI key metadata. The secret is never included; only its last four characters.
Example: {"id":"8f4c2a19d7e34b6f","keyId":"8f4c2a19d7e34b6f","name":"Zapier production key","description":"Used by the Zapier integration","secretLast4":"Q9xA","accountId":"6b3e1a9d4c7f42e8a5d0c1f9b2e7a4c6","permissions":["prospects:read","prospects:write"],"keyFormat":"v2","createdAt":1717000000000,"lastUsedAt":1717014400000,"deletedAt":null,"deleteScheduledAt":null,"deleteExpiresAt":null,"status":"active","active":true,"keyType":null,"usage":null,"systemManaged":false,"hiddenFromSettings":false}
Update API Key
Changes the name and/or description of the API key you are calling with. Any key may rename
itself, whatever its scopes. The secret cannot be changed here (use rotate), and a key cannot
change its own scopes (403); change scopes in Settings. PATCH /api-keys/{keyId} is also
accepted with the same body and behavior.
The keyId must be the key you are calling with; any other key returns 403.
path Parameters
keyIdstring · requiredThe id of the key you are calling with (
idfromGET /auth).Example: 8f4c2a19d7e34b6f
Headers
X-Idempotency-KeystringOptional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P
Request Body
namestring · minLength: 1 · maxLength: 100Example: Zapier key (renamed)descriptionstring · maxLength: 500Example: Rotated quarterly
Responses
OK
successboolean · requiredmessagestring · requiredkeyobject · requiredAPI key metadata. The secret is never included; only its last four characters.
Example: {"id":"8f4c2a19d7e34b6f","keyId":"8f4c2a19d7e34b6f","name":"Zapier production key","description":"Used by the Zapier integration","secretLast4":"Q9xA","accountId":"6b3e1a9d4c7f42e8a5d0c1f9b2e7a4c6","permissions":["prospects:read","prospects:write"],"keyFormat":"v2","createdAt":1717000000000,"lastUsedAt":1717014400000,"deletedAt":null,"deleteScheduledAt":null,"deleteExpiresAt":null,"status":"active","active":true,"keyType":null,"usage":null,"systemManaged":false,"hiddenFromSettings":false}
Delete API Key
Deactivates the API key you are calling with. It stops authenticating immediately, so this is the
last request it makes. Any key may delete itself, whatever its scopes; deleting a key created by
connecting an AI tool (MCP) disconnects that tool. An admin or owner can restore the key in
Settings for 30 days (until deleteExpiresAt); after that it is permanently removed.
The keyId must be the key you are calling with; any other key returns 403.
path Parameters
keyIdstring · requiredThe id of the key you are calling with (
idfromGET /auth).Example: 8f4c2a19d7e34b6f
Headers
X-Idempotency-KeystringOptional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P
Responses
OK
successboolean · requiredmessagestring · requiredkeyobject · requiredAPI key metadata. The secret is never included; only its last four characters.
Example: {"id":"8f4c2a19d7e34b6f","keyId":"8f4c2a19d7e34b6f","name":"Zapier production key","description":"Used by the Zapier integration","secretLast4":"Q9xA","accountId":"6b3e1a9d4c7f42e8a5d0c1f9b2e7a4c6","permissions":["prospects:read","prospects:write"],"keyFormat":"v2","createdAt":1717000000000,"lastUsedAt":1717014400000,"deletedAt":null,"deleteScheduledAt":null,"deleteExpiresAt":null,"status":"active","active":true,"keyType":null,"usage":null,"systemManaged":false,"hiddenFromSettings":false}
Rotate API Key
Replaces the key's secret and returns the new full key once, in key. The key id, name, and
permissions stay the same. The previous secret stops working immediately, with no grace period,
so update your integration right away. Only active keys in the hc_<keyId>.<secret> format
(keyFormat: v2) can be rotated. Any key may rotate itself, whatever its scopes.
The keyId must be the key you are calling with; any other key returns 403.
Retrying with the same X-Idempotency-Key within 24 hours returns the original response
instead of rotating again.
path Parameters
keyIdstring · requiredThe id of the key you are calling with (
idfromGET /auth).Example: 8f4c2a19d7e34b6f
Headers
X-Idempotency-KeystringOptional. Client-generated key that makes retries of this request safe. The first response for the key is stored for 24 hours and replayed for retries with the same method, path, query, and body. Reuse a key only when retrying the exact same request.
Example: idem_prospect_create_01HV6W0J7Y7A5Q3T4J6N8M2P
Responses
OK
successboolean · requiredmessagestring · requiredkeystring · requiredThe new full API key (
hc_<keyId>.<secret>). The key id is unchanged. It is returned only in this response, so store it securely now.Example: hc_8f4c2a19d7e34b6f.Pm7wE4cY2tHq9Rb1nUa6Lk3Didstring · requiredExample: 8f4c2a19d7e34b6fnamestring · requiredpermissionsstring[] · requiredPermissions stored on the key (see
ApiKey).createdAtinteger | null · int64 · requiredUnix timestamp in milliseconds when the key was first created.
activeboolean · required