Settings — API Keys

The Settings ▸ API Keys page is the admin surface for managing programmatic access to your tenant. Each issued key is a scoped credential that backend systems use to call the Athenty REST API for verifications, envelopes, clients, webhooks, and adjacent endpoints.

The page is plan-gated to Professional or higher. Starter tenants see an upgrade banner with a link to Settings ▸ Billing; Pro+ tenants see the full management surface.

Anatomy of the page

1. Page header

Standard PageHeader with the title API Keys and a one-line description. The New Key button sits to the right.

2. Plan-gated empty state

If the tenant’s plan tier is below Professional, the body renders an upgrade card instead of the management UI. The card links to Settings ▸ Billing.

3. Keys list

When the plan supports it, the body renders the issued-keys list:

• Name + description
• Mode pill (Live / Test)
• Scopes badge group
• Created, last-used, created-by columns
• Status pill (Active / Revoked)
• Row actions: Copy ID · Edit · Revoke

4. Create / view-secret dialog

A single dialog handles both flows:

• Create — name + mode + scopes form
• View secret — shown once with a copy button immediately after creation, then never again

Live vs Test mode

Two parallel keysets. The mode is encoded in the key itself; no header switch.

Mode	Affects	Billing
Live	Production records	Yes — counts toward plan
Test	Sandbox records	No — free

Test mode is the right default for development, CI, integration tests, and staging traffic. Live mode is only for production.

Scope model

Scopes are typed strings, evaluated at request time against the endpoint’s required scope. Built-in scopes:

Scope	Capabilities
*	All endpoints
verifications:read / :write	Verification list/get vs create/update/cancel
envelopes:read / :write	Envelope read vs create/update/cancel/send
clients:read / :write	Client read vs create/update/delete
webhooks:write	Webhook CRUD
audit:read	Read audit log

Wildcard * is granted by default on new keys for convenience but should be narrowed for production integrations.

Secret-handling design

The platform stores only the hashed secret on the key record:

1. On create, a random 32-byte secret is generated server-side
2. The hash (bcrypt + per-tenant salt) is stored
3. The plaintext secret is returned in the create response only
4. On every API call, the platform hashes the inbound key + compares to stored — no secret ever lives in plaintext server-side after the create response

This means Athenty operators cannot recover a lost secret. The recommended workflow is: lose secret → issue new + revoke old.

Rotation pattern

Recommended rotation for production:

1. Issue a new key with the same scopes
2. Update your backend to use the new key
3. Wait for in-flight requests on the old key to drain (typically minutes)
4. Revoke the old key

There’s no built-in graceful overlap — both keys are simultaneously valid until you revoke one. Plan rotations during low-traffic windows or during a regular deployment.

Permissions and scope

Role	View	Create	Revoke
Owner / Admin	✓	✓	✓
Member	✗	✗	✗
Viewer	✗	✗	✗

Audit logging

Action	Event
Create	api_key.created (with mode + scopes; never the secret)
Update	api_key.updated
Revoke	api_key.revoked

Events surface in Settings ▸ Audit Log. Audit events do not contain the secret — by design.

Troubleshooting

Symptom	Most likely cause	Fix
API Keys page shows upgrade card	Plan is Starter	Upgrade in Settings ▸ Billing
Lost secret post-creation	Shown once only	Issue new key + revoke old
401 on API call	Key revoked, wrong mode, or bad header format	Verify key + mode + Authorization header
403 on API call	Scope missing for the endpoint	Add scope or use *
Test traffic billed	Using Live key in test env	Audit your key segregation

Related pages

• Settings ▸ Billing — plan tier gates this page
• Settings ▸ Webhooks — adjacent integration surface
• Settings ▸ Audit Log — api_key.* events