Skip to content

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 ​

NameTypeDescription
targetPathstringRequired target containing the API key.
apiKeyIdstringRequired for get, revoke, and delete. The key record's ID, consisting of 32 lowercase hexadecimal characters.
body.namestringRequired for create. Contains 1–100 characters after trimming.
body.expiresAtnumberOptional 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.permissionNamesstring[]Optional for create. Nonempty array of supported user permission names. Defaults to ["READ"].
query.cursorstringOptional 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:

OperationHTTP statusdatamessage
Create201{ secret, key }, where secret is the key metadata and key is the complete plaintext credential.API key created
List200{ secrets, nextCursor }, where secrets is an array of key metadata and nextCursor is a string or null.API keys retrieved
Get200The key metadata.API key retrieved
Revoke204No response body.None
Delete204No 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 revokedAt and 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}/secrets
get/api/{targetPath}/secrets
get/api/{targetPath}/secrets/:apiKeyId
post/api/{targetPath}/secrets/:apiKeyId/revoke
delete/api/{targetPath}/secrets/:apiKeyId