Authentication

Programs authenticate with API keys. A key acts as the member who created it, limited to the permissions you give the key. There is no token exchange: the key itself is the credential, sent on every call.

API keys are managed by administrators on API Keys (in the Developer part of the menu). Creating keys needs a plan with API keys.

Create a key

1. Open API Keys and select New API Key.
2. Enter a Name (up to 100 characters) and, optionally, a Description (up to 500).
3. Under Module permissions, pick what the key may do, a module at a time. Each module offers a Read only preset; you can also tick single permissions. Use Search modules or permissions… to find one. The picker lists only permissions you hold yourself: “The key can do at most what you can do. If your own rights shrink later, the key loses them too.”
4. Set Expires on. The default is 90 days from today, at most a year (“90 days by default, at most a year.”).
5. Optionally fill IP allowlist: one subnet per line, for example 10.0.0.0/8 or 203.0.113.7/32. Empty means any address your organisation allows.
6. Leave Integration scopes (advanced) empty unless an integration’s own documentation asks for one (for example SCIM provisioning).
7. Select Create Key and copy the key now.

If you have two-factor authentication or a passkey, Hermetry asks you to confirm it before the key is made. A key cannot be created while you are impersonating a member.

Key format

sk_live_<first 8 characters of the organisation id>_<48 random hexadecimal characters>

live keys belong to the production service, test keys to test installations, so the two cannot be mistaken for each other.

Use a key

Send the key in the Authorization header on every call:

curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
  -H "Authorization: Bearer sk_live_…"

• A request with an API key is judged only as that key. A browser cookie on the same request is ignored.
• Keys work only on your organisation’s paths (/tenant/<tenantId>/api/...). The key’s organisation must match the tenantId in the path.
• A key never works on platform, account or sign-in routes.

What a key may do

On every call, all of these must hold:

1. The key holds the permission the route needs.
2. The permission’s module is switched on for your organisation.
3. The member who created the key holds the permission now: their role, their groups and your access policies count.
4. The member is still an active member and the organisation is active.

A key acts with at most the Admin role, even when an Owner created it. So a key can never hold Owner-only permissions (for example raw device commands, firmware signing keys, dangerous device settings, rotating a webhook secret), and never permissions of the identity and access modules (sign-in, accounts, API keys, members, sessions). A key therefore cannot create or rotate keys.

Service keys

A key normally stops working when its creator leaves the organisation. An Owner can open the key and select Mark as service key: it then keeps working after its creator leaves (“Yes: survives its creator”) and acts as the Owner who marked it.

Allowed networks

A key’s IP allowlist holds up to 100 subnets in CIDR form; a single address is /32. Calls from anywhere else are refused with 403 “This API key may not be used from the current IP address.” A key without its own list uses the organisation’s default list (see Settings below). Your organisation’s own IP allow and deny lists for sign-in also apply to keys.

Expiry

Every key expires. The default is 90 days; the latest date is 365 days ahead, or less if your organisation sets a lower maximum. Expired keys stop by themselves. An administrator can also sweep expired keys (POST /api/api-keys/sweep-expired) to mark them inactive and send one api_key.expired webhook event per key.

Rotate, deactivate and revoke

Open a key to see its Identity, Usage (last used, last used IP, total verifications), Module permissions and Rotation history.

• Rotate key creates a successor with the same permissions, scopes, network list and environment. Set the Grace window (days): the old key keeps working until it ends. “0 revokes the old key immediately.” Copy the new secret at once.
• Deactivate stops a key until you Activate it again. A rotated key cannot be reactivated: “A rotated key cannot be reactivated; use its successor.”
• Revoke deletes the key: “Any integrations using this key will immediately stop working. This action cannot be undone.”
• Edit changes the key’s module permissions. You can remove any permission, and add only permissions you hold. Integration scopes can only be narrowed.

In an incident, an administrator can revoke every active key of the organisation in one step.

{
    "graceSeconds": 86400
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/{apiKeyId}/rotate' \
  -H 'Content-Type: application/json' \
  -d '{"graceSeconds":86400}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Only an active, unexpired key that has not been rotated yet can be rotated.",
    "code": "CONFLICT"
}

Manage keys over HTTP

Keys are managed by a signed-in administrator. An API key cannot create, change or rotate keys.

{
    "name": "Plant ERP",
    "permissions": [
        "iot_device.devices.read",
        "telemetry.read"
    ],
    "ipAllowlist": [
        "203.0.113.0/24"
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Plant ERP","permissions":["iot_device.devices.read","telemetry.read"],"ipAllowlist":["203.0.113.0/24"]}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Select at least one module permission or integration scope."
}

{
    "message": "An API key can only receive permissions you hold yourself."
}

{
    "message": "The expiry date must be in the future."
}

Check a key

{
    "scope": "read"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/verify' \
  -H 'Content-Type: application/json' \
  -d '{"scope":"read"}'

{
    "valid": true,
    "key": {
        "name": "Plant ERP",
        "…": "…"
    }
}

{
    "valid": false,
    "message": "scope must be a string"
}

{
    "valid": false,
    "message": "Invalid or expired API key."
}

{
    "valid": false,
    "message": "Too many requests."
}

Settings

Administrators set the organisation’s key policy on API Keys > settings (the gear button):

The other limits that apply to keys are in Errors and rate limits.

Watching keys

• Each key records when and from which address it was last used.
• A key unused for 14 days and then used from a new address raises an audit event (“A dormant API key was used from a new address”), at most once per key and address per hour.
• Every refused key call is written to the audit log.
• Webhooks can tell you about keys: api_key.created, api_key.updated, api_key.rotated, api_key.deleted, api_key.expired.

See API key hardening for a checklist.