Hank
_CONSOLEbeta

Authentication

Every request authenticates with an API key sent as a bearer token:

Authorization: Bearer <YOUR_API_KEY>

Creating and managing keys

Create, rename, rotate, and revoke keys at API Keys. Click + New key, then click Create key. The key is shown in full once, at creation. Copy it then. Only its SHA-256 hash is stored, so it can never be displayed again.

Revoke a key the moment it might be exposed. A revoked key stops working immediately: its next call returns 401. The key list hides revoked keys. Click Show revoked keys to see them.

Your key list also shows the keys an operator at Hank created for your organization. These carry a created by your admin badge. You can revoke them, so check with your organization first: another team may depend on one.

Rotate a key

Rotate replaces a key's secret and keeps everything else about it: the same name, the same services, the same limits, and the same expiry date. The new token is shown once, exactly like a new key. The old token is revoked at the same moment, so put the new one into your integration immediately. To change integrations first and cut over later, create a second key instead of rotating.

You cannot rotate a key that is revoked, expired, or suspended. You also cannot rotate a key that carries the "created by your admin" tag: only your Hank admin can rotate it, because they deliver the new secret to the system that uses it. You can still revoke such a key if you think it leaked.

Expiry

You can give a key an optional future expiry date at creation. An expired key returns 401. Leave the date blank for a non-expiring key.

Scopes

A key can be scoped to specific services. Select the services on the create form. If you select none, the key gets every service your plan includes at that moment, written onto the key as an explicit list.

That list is fixed for the life of the key. If your plan adds a service later, an existing key still cannot call it. Create a new key to use the new service. A plan downgrade does not widen a key either: the key can never reach more than its own list.

You can only scope a key to services your plan entitles you to. The service checkboxes on the create form list exactly those.

A call returns 403 when the key is not scoped to that service, or when your plan does not include it. See Errors. Per-service usage limits on a key are covered in Rate limits.

Accepting the Terms of Service

Before any key on your account can make a billable API call, your organization must accept the current Terms of Service and Privacy Policy. Acceptance is a one-time action per organization. Once it's on file, every key under the account is cleared.

Until then, the first call to a /v1/<service>/ endpoint returns 451, with the accept URL in a response header:

HTTP/1.1 451 Unavailable For Legal Reasons
X-Hank-Tos-Required: 1
X-Hank-Tos-Accept-Url: https://console.hank.ai/legal/accept

<h1>451</h1><p>Terms of Service acceptance required before using this service.</p>

The body is a short HTML notice; the part to act on is the X-Hank-Tos-Accept-Url header. Open it, sign in, check the box to accept, and submit. The acceptance is recorded against your organization. Retry the call and it proceeds. You only do this once, not per key and not per service.

A few things worth knowing:

  • The Terms gate runs before the scope, plan, and credit checks. A 451 means consent is missing, not that your key is mis-scoped or out of credits. A perfectly valid, in-credit key still returns 451 until the Terms are accepted. Fix the consent first, then worry about 403 / 402.
  • You read the Terms without signing in. Terms of Service and Privacy Policy are public pages; only recording your acceptance requires a console sign-in.
  • Anyone on the organization can accept. It's recorded for the whole account, so a teammate accepting clears the gate for every key you have created.
  • A new version re-gates you. If Hank publishes an updated Terms or Privacy Policy, the next billable call returns 451 again until the new version is accepted. The response header always points you back to the accept page.

For the bare status-code reference, see Errors.

Keep keys secret

  • Never commit a key to source control.
  • Never expose a key in client-side / browser code.
  • Use a separate key per environment so you can revoke one without disrupting others.