Create an API key

What this achieves

An API key lets another system read from or write to Humavera without a person signing in. Each key carries its own scopes, rate limit, and expiry date, so a key grants only what its integration needs.

Required role: Administrator.

Steps

Go to Integrations → API Keys.
Select Create Key.
Enter a Name describing what will use the key.
Choose the Scopes.
Set an Expiry date.
Set the Rate Limit (req/hr).
Select Save.
On the API Key Created dialog, select Copy to Clipboard, store the key, tick the acknowledgement, and select Done.

Scopes

Scopes are grouped by area, and each is a read or write grant on one kind of record.

Group	Scopes
Employees	`employees:read`, `employees:write`, `employees:*`
Skills & Competencies	`skills:read`, `skills:write`, `competencies:read`, `competencies:write`
Learning	`courses:read`, `enrollments:read`, `enrollments:write`, `assessments:read`
Feedback	`feedback:read`, `feedback:write`
Workflows	`workflows:read`, `workflows:write`
Mobility	`mobility:read`, `mobility:write`
Full Access	`*`

A scope ending in :* grants every operation on that resource. The * scope grants everything.

Grant the narrowest set that works. A reporting pipeline that reads headcount needs employees:read and nothing else; giving it * because it was quicker means a leaked key writes as well as reads.

Example: HC Corp’s finance reporting job runs on employees:read. If that key ends up in a log file, the worst case is that somebody read a list. On *, the worst case is unbounded.

Rate limit and expiry

Option	Description
Name	What uses this key. Shown in the list and in usage analytics.
Scopes	What the key may do.
Expiry	The date the key stops working.
Rate Limit (req/hr)	Requests per hour this key may make. Shown in the list as a per-hour figure.

Set an expiry. A key with a distant expiry is a credential nobody will ever reconsider, and rotation you have scheduled is far less disruptive than rotation forced by an incident.

The rate limit caps one integration’s share of capacity, so a runaway job cannot exhaust it for everything else. Set it to what the integration actually needs plus headroom, not to the largest number the field accepts.

Name the key for its consumer, not for the person creating it. “Analytics Pipeline” tells the next administrator what breaks if they revoke it; “Priya’s key” does not.

The key is shown once

When the key is created, the dialog shows it with a warning to copy it now because you will not see it again. Keys are stored hashed — the list shows only enough to identify a key, never the key itself.

There is no way to retrieve the key afterwards. If it is lost, the only route is to revoke it and create a new one, which means updating whatever was using it.

Copy it into wherever your integration reads its credentials before you select Done. The acknowledgement checkbox is there because this is the one moment the value exists on screen.

Revoking a key

Select the revoke action beside a key and confirm.

The interface states what that does: revoking immediately breaks any integration using the key, and it cannot be undone. Revoked keys stay in the list marked as already revoked.

Revoke immediately where a key may have leaked, and accept the breakage. A key you are unsure about is a key to replace, not to monitor.

Example: if HC Corp’s payroll reporting key appears in a shared log, revoke it, create a replacement with the same scopes, and update the job. The reporting run fails once; the alternative is a credential you know is exposed staying live.

What monitoring you get

The list shows each key’s scopes, status, rate limit, expiry, and when it was last used. Last Used: Never on a key that has been live for weeks means either the integration was never finished or it is using a different key — both worth resolving rather than leaving in place.

What happens next

The key can authenticate requests immediately, within its scopes and rate limit. Usage is logged per key and readable on the API usage page, including which endpoints were called and what they returned. Set a reminder before the expiry date, because an expiring key stops its integration without warning anyone.