API reference
API keys
Secret keys with scopes that authenticate requests from your servers and workers.
Overview
API keys authenticate your requests. Each key belongs to one mode, test or live, and carries scopes that limit what it can do, so a worker that only creates jobs never needs a key that can delete webhooks.
The full key is shown once, in the secret field of the create response. After that only a redacted form is available. Managing keys requires a key with the keys:write scope.
- Endpoints
- 3
- ID prefix
- key_
- Attributes
- 12
The API key object
Every API key endpoint returns this object, or a list of them. Attributes marked null are always present in the response, so you can rely on the shape.
Attributes
idstringUnique identifier, prefixed with key_.
objectstringAlways api_key.
namestringA label for your team, such as Billing worker.
modeenumtest or live.
redactedstringThe prefix and last four characters, such as hy_test_…Q7mP.
scopesstring[]What the key may do, such as jobs:write. * grants everything.
secretstringThe full key. Only present in the create response.
created_bystringEmail of the teammate who created it.
created_attimestampWhen the object was created, in ISO 8601 UTC.
last_used_attimestamp | nullLast authenticated request, accurate to the minute.
expires_attimestamp | nullWhen the key stops working, or null if it doesn't expire.
revoked_attimestamp | nullWhen the key was revoked.
{ "id": "key_4Wp7Ns2Hb8", "object": "api_key", "name": "Billing worker", "mode": "test", "redacted": "hy_test_…Q7mP", "scopes": [ "jobs:write", "events:write" ], "created_by": "mira.okafor@larkspur.example", "created_at": "2026-10-01T11:18:40Z", "last_used_at": "2026-10-14T09:12:03Z", "expires_at": null, "revoked_at": null}Create an API key
/v3/api_keysCreates a key in the same mode as the key making the request. Copy the secret from the response; it can't be retrieved again.
Body parameters
namestringrequiredA label, up to 80 characters.
scopesstring[]default: ["*"]Such as jobs:read, jobs:write, events:write, keys:write.
expires_attimestampOptional expiry, at least one hour ahead.
Returns
The API key object, including the one-time secret.
curl https://api.halyard.example/v3/api_keys \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \ -H "Content-Type: application/json" \ -d '{ "name": "Billing worker", "scopes": [ "jobs:write", "events:write" ] }'import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const key = await halyard.apiKeys.create({ name: "Billing worker", scopes: ["jobs:write", "events:write"],});import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) key = halyard.api_keys.create( name="Billing worker", scopes=["jobs:write", "events:write"],){ "id": "key_4Wp7Ns2Hb8", "object": "api_key", "name": "Billing worker", "mode": "test", "redacted": "hy_test_…Q7mP", "scopes": [ "jobs:write", "events:write" ], "created_by": "mira.okafor@larkspur.example", "created_at": "2026-10-14T10:20:00Z", "last_used_at": null, "expires_at": null, "revoked_at": null, "secret": "hy_test_9Vd3Kw7Rb2Xn5Tq8Q7mP"}List API keys
/v3/api_keysLists keys in the current mode, including revoked ones from the last 90 days.
Query parameters
revokedbooleanfalse to hide revoked keys.
limitintegerdefault: 20How many objects to return, between 1 and 100.
starting_afterstringA cursor: the ID of the last object on the previous page. The next page starts right after it.
ending_beforestringA cursor for paging backwards: the ID of the first object on the current page.
Returns
A list object with API key objects in data.
curl -G https://api.halyard.example/v3/api_keys \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \ -d revoked=false \ -d limit=10import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const keys = await halyard.apiKeys.list({ revoked: false, limit: 10,});import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) keys = halyard.api_keys.list(revoked=False, limit=10){ "object": "list", "url": "/v3/api_keys", "has_more": false, "data": [ { "id": "key_4Wp7Ns2Hb8", "object": "api_key", "name": "Billing worker", "mode": "test", "redacted": "hy_test_…Q7mP", "scopes": [ "jobs:write", "events:write" ], "created_by": "mira.okafor@larkspur.example", "created_at": "2026-10-01T11:18:40Z", "last_used_at": "2026-10-14T09:12:03Z", "expires_at": null, "revoked_at": null }, { "id": "key_8Jr2Fx6Lm1", "object": "api_key", "name": "CI deploys", "mode": "test", "redacted": "hy_test_…w2Kd", "scopes": [ "queues:write" ], "created_by": "theo.lindqvist@larkspur.example", "created_at": "2026-07-19T15:02:44Z", "last_used_at": "2026-10-13T22:47:00Z", "expires_at": "2027-01-01T00:00:00Z", "revoked_at": null } ]}Revoke an API key
/v3/api_keys/{id}/revokeRevokes a key immediately. Requests made with it fail with 401 api_key_revoked within a few seconds, everywhere.
Path parameters
idstringrequiredThe key's ID. A key can't revoke itself.
Returns
The API key object with revoked_at set.
curl -X POST https://api.halyard.example/v3/api_keys/key_4Wp7Ns2Hb8/revoke \ -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const key = await halyard.apiKeys.revoke("key_4Wp7Ns2Hb8");import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) key = halyard.api_keys.revoke("key_4Wp7Ns2Hb8"){ "id": "key_4Wp7Ns2Hb8", "object": "api_key", "name": "Billing worker", "mode": "test", "redacted": "hy_test_…Q7mP", "scopes": [ "jobs:write", "events:write" ], "created_by": "mira.okafor@larkspur.example", "created_at": "2026-10-01T11:18:40Z", "last_used_at": "2026-10-14T09:12:03Z", "expires_at": null, "revoked_at": "2026-10-14T10:31:08Z"}