Appearance
API Keys
Create, list, retrieve, revoke, and permanently delete API keys. Authentication and ADMIN access to the requested target are required. An API key with the required access can also manage keys.
Supported target paths are site/:siteId, tenant/:tenantId, tenant/:tenantId/division/:divisionId, organization/:orgId, organization/:orgId/tenant/:tenantId, and organization/:orgId/tenant/:tenantId/division/:divisionId. Management returns only keys created for the exact requested target, including when the caller can administer its descendants.
Parameters
| Name | Type | Description |
|---|---|---|
targetPath | string | Required target containing the API key. |
apiKeyId | string | Required for get, revoke, and delete. The key record's ID, consisting of 32 lowercase hexadecimal characters. |
body.name | string | Required for create. Contains 1–100 characters after trimming. |
body.expiresAt | number | Optional for create. Future Unix timestamp in milliseconds, at most one UTC calendar year plus one day away. Defaults to six UTC calendar months away. |
body.permissionNames | string[] | Optional for create. Nonempty array of supported user permission names. Defaults to ["READ"]. |
query.cursor | string | Optional for list. Use the previous response's nextCursor to request the next page. |
Create accepts only name, expiresAt, and permissionNames; unknown fields are rejected. expiresAt: null is rejected. Permission names can include ADMIN, MANAGE_TRAINING, and SUPER_ADMIN; unknown names are rejected and duplicates are removed. Permissions belong to the key rather than the user who created it.
Keys cannot be edited. Revoke and recreate a key to change its settings. Get, list, revoke, and delete require no request body.
Return Value
Successful create, list, and get responses contain data and message:
| Operation | HTTP status | data | message |
|---|---|---|---|
| Create | 201 | { secret, key }, where secret is the key metadata and key is the complete plaintext credential. | API key created |
| List | 200 | { secrets, nextCursor }, where secrets is an array of key metadata and nextCursor is a string or null. | API keys retrieved |
| Get | 200 | The key metadata. | API key retrieved |
| Revoke | 204 | No response body. | None |
| Delete | 204 | No response body. | None |
Metadata contains id, name, permissionNames, claim (the key's permission claim), prefix (a display prefix), createdBy (the creator's identity), createdAt, updatedAt, expiresAt, and revokedAt. Timestamps are Unix milliseconds. revokedAt is null until revocation; expiresAt can be null for an existing nonexpiring key, although new keys must expire.
Only creation returns the complete credential; copy it before leaving the response. Responses never include the credential hash. All management responses, including errors, carry Cache-Control: no-store. Direct Firestore client access to key records is denied, including for admins.
List returns up to 25 records, including expired and revoked keys. Unrevoked keys come first, then revoked keys; each group is ordered by newest creation time, with ID as a tie-breaker. nextCursor is null when no further page exists. Page size is fixed.
Authentication and Lifecycle
Send the complete credential using Authorization: Bearer <api-key>. Keys start with wt_; use the full value as returned by creation.
Existing endpoint permission checks apply. ADMIN access can authorize descendants of the selected target. Division keys cannot authorize parent or sibling targets, and site keys remain within their site.
- Revocation records
revokedAtand keeps the key visible in management responses. Repeated revocation succeeds and preserves the original timestamp. - Deletion permanently removes a key, whether or not it was revoked first, and cannot be undone.
- Revocation and deletion can take up to five minutes to stop authentication across instances because verification is cached. Expiration is checked on every request, including cached requests.
Error Codes
400: Invalid create body, expiration, permission names, API key ID, or pagination cursor.401: Missing or invalid authentication, a revoked or expired credential once the change applies, or insufficient permissions for the requested target.404: The requested key does not exist or belongs to another target. Create also returns this status if the target does not exist.
Examples
Create a read-only key using the default six-month expiration:
bash
curl -X POST "https://app.wombat.software/api/{targetPath}/secrets" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <admin-token>" \
-d '{"name":"Reporting integration","permissionNames":["READ"]}'ENDPOINTS
post
/api/{targetPath}/secretsget
/api/{targetPath}/secretsget
/api/{targetPath}/secrets/:apiKeyIdpost
/api/{targetPath}/secrets/:apiKeyId/revokedelete
/api/{targetPath}/secrets/:apiKeyId