Setup Considerations: API access and secrets

What this achieves

Every credential you issue is a way for data to leave your workspace, and every one of them is shown exactly once. This page covers choosing the right mechanism, granting the least access that works, and planning rotation before an incident forces it.

Decision 1: which mechanism the integration actually needs

The question is what triggers the exchange, not which one is most capable.

Option	Description
Webhook	Humavera tells another system the moment something happens. Outbound, event-driven. No credential is issued to anyone — you hold a signing secret so the receiver can verify the message.
API key	Another system asks Humavera for data. One static secret, scoped and rate-limited. Simplest, and the right answer for a job you control.
OAuth app	A client identity with a rotatable secret, and the option to act on behalf of a signed-in person. More setup. The right answer for a third-party application, or where consent matters.
Import and export	Bulk movement, run on demand. No standing credential at all.

Example: HC Corp wanting its service desk to open an account when someone joins needs a webhook, not a key. A key would mean the service desk polling for new employees, which is more credential, more traffic, and slower.

Prefer the mechanism that issues no standing credential. A webhook and a scheduled export both move data without anyone holding a key that works until someone revokes it.

Decision 2: scope granularity

Scopes are per-resource and per-action, with wildcards available at resource level (employees:*) and globally (*).

Option	Description
Named read scopes	The narrowest useful grant. A leaked credential reads one kind of record.
Named read and write	Where the integration genuinely writes back.
Resource wildcard	Every operation on one resource. Convenient, and broader than most integrations need.
Global wildcard	Everything. Justify it or do not issue it.

The wildcard is not a shortcut you pay for later — it is a decision about what a leaked credential does. Both a read scope and a global wildcard behave identically until something goes wrong.

Example: HC Corp’s finance reporting job on employees:read leaks, and somebody read a list. The same job on * leaks, and the exposure is the entire workspace, in both directions.

Issue one credential per consumer, not one shared key. A shared key cannot be revoked without breaking everything that holds it, which in practice means it is never revoked.

Decision 3: lifetimes and rotation

Every secret in this section is shown once and cannot be retrieved.

Credential	What the product does
API key	Shown once at creation, stored hashed. Lost means replaced, not recovered. Carries an expiry date you set.
OAuth client secret	Shown once at registration. Regenerate Secret invalidates the current one immediately and shows a new one once.
Webhook signing secret	Set or auto-generated at creation. Not shown back in the form on a later edit.
Service-provider private key	Encrypted at rest and never returned in plaintext.

Set expiry dates on keys, and set them somewhere you will actually be reminded. A key with a distant expiry is a credential nobody will reconsider until it stops working, which will be during something else.

Plan a rotation as a short, scheduled outage on that one integration. There is no overlap period on an OAuth secret — the old one dies the moment the new one is issued, so the update has to follow immediately.

Example: rotating HC Corp’s reconciliation app secret with the new value ready to paste costs nothing. Rotating it and discovering the person who maintains the consumer is on leave costs a week of a broken nightly job.

Decision 4: who may hold a credential, and where it lives

The product does not know where your secrets are stored, and it cannot help you once they leave the reveal dialog. That makes two things policy rather than configuration.

Decision	Why it has to be settled now
Who may create keys and apps	Every administrator can. Decide whether that means every administrator should.
Where a secret is stored on receipt	The reveal dialog is the one moment the value exists. If there is no agreed destination, it goes wherever was convenient.

Name keys for what consumes them. “Analytics Pipeline” tells the next administrator what breaks if they revoke it. A key named after a person tells them nothing and stops being accurate when that person changes role.

Decision 5: what you review, and how often

Credentials accumulate. Nothing in the product expires an unused key before its date.

Three checks worth scheduling:

Keys showing Last Used: Never, or nothing recent. Either the integration was never finished or it has stopped — both worth resolving rather than leaving live.
Requests from an origin you do not recognise on a key you believed one system held. That is a revoke, not an investigation.
Webhooks whose status is paused or whose last delivery is old. A paused webhook is silent in exactly the way a quiet one is.

What is expensive to change later

Decision	Cost of changing later
A leaked secret	High and immediate. Revoke breaks the integration instantly and cannot be undone — which is the correct trade, and it is still an outage.
Narrowing a credential’s scope	Low technically. Medium in practice, because you have to know what the consumer actually calls before you take something away.
One shared key across several consumers	High. It cannot be revoked without breaking all of them, so it survives longer than it should.
Rotating an OAuth client secret	Medium. No overlap period, so the consumer update has to follow immediately.
An expiry date set far out	Low to change, high in effect — it postpones the review that would have caught an unused credential.

What happens next

Issue the narrowest credential the integration needs, store the secret where your organization agreed it goes, and record what consumes it and when it expires. Then use the usage and delivery pages to confirm it is doing what you expected, because a credential that was issued and never used is the one nobody will think to revoke.