Skip to content

Admin API Keys

Enterprise administrators can create, view, filter, and revoke API keys on behalf of any user via the dedicated admin panel at /admin/api-keys. This guide covers the full admin workflow, including scope assignment and audit trail visibility.

Access Control

/admin/api-keys requires the admin role (or admin:api-keys scope). Non-admins are automatically redirected to /settings/api-keys (their personal keys page).

API access is protected by the same scope: POST, PATCH, and DELETE operations on /api/v1/admin/api-keys* endpoints require admin authorization.

Creating an API Key

Step 1: Open Create Modal

  1. Navigate to Admin → API Keys in the sidebar
  2. Click + Create API key (top right)

Step 2: Complete the Form

Fill in the required fields:

  • User — Search by email (combobox with autocomplete). Shows user role badge.
  • Label — Descriptive name (1–80 chars); shown in lists and audit logs. Example: ci-bot, data-sync, webhook-monitor.
  • Scopes — At least one required. Multi-checkbox list from the /api/v1/scopes endpoint. Privileged scopes (e.g., admin:*) are grouped under "Privileged scopes" with a warning icon.
  • Important: Admins cannot grant scopes they themselves don't hold. This is a ceiling rule enforced by the API. If you lack write:artifacts, you cannot create a key with write:artifacts.
  • Expires — Radio group: Never / In 30 days / In 90 days / Custom date picker. Defaults to 30 days.

Step 3: Confirm Key Reveal

After clicking Create, the form transitions to a one-time key reveal screen:

Key:  skm_live_a1b2c3d4e5f6...
  • Click Copy to copy the full key to the clipboard.
  • Check "I have copied the key to a secure location" to enable the Done button.
  • You will not be able to view this key again. If lost, you must create a new one.

If you close the dialog before copying the key, a confirmation appears: "Close without saving the key?" confirms that the key is unrecoverable. Click Close anyway only if you want to discard it.

Viewing and Filtering Keys

List View

The list displays all API keys in your enterprise, with columns for:

Column Details
Label User-provided name; "—" if blank
User Owner's email; "(deleted)" if user was removed
Prefix First 16 chars of the key (e.g., skm_live_a1b2...); "—" if hidden by API contract
Scopes Assigned scopes as chips; +N overflow indicator for space-constrained displays
Status Active, Revoked, Expired, or Unknown badge
Last Used Relative timestamp (e.g., "2 hours ago"); "Never" if not yet used
Action Revoke button (disabled if already revoked)

Filtering

Active keys (top bar):

  • User — Combobox filter; select one user or leave blank for all users. Clears via the × button in the input.
  • Scope — Multi-select popover of all available scopes. Filters to keys matching all selected scopes (AND logic).
  • Active — Radio group: Any (default) / Active / Revoked. Excludes the param from the URL when set to "Any".
  • Created date range — From / To date inputs (inclusive). Leave blank to omit from the query.

Click Apply to commit filters and refetch. Filters auto-apply after 250ms of inactivity. Click Reset to clear all filters.

All filters are serialized to the URL query string and are bookmarkable.

Pagination

Server-side pagination with a limit of 25 keys per page. Use the numbered page controls or prev/next buttons to navigate.

Revoking a Key

  1. Locate the key in the list
  2. Click the Revoke button in the row's Action column
  3. A confirmation dialog appears with key details (label, user, prefix)
  4. Click Revoke key to confirm

Revocation is immediate and irreversible. Any clients using the revoked key will receive 401 responses starting immediately.

The key's Status badge updates to "Revoked" in the list, and the Revoke button becomes disabled.

Scope Ceiling Rule

When creating or editing a key's scopes, the API enforces a scope ceiling: admins cannot grant scopes they themselves do not hold.

Example: - If your admin account has scopes [read:artifacts, deploy:artifacts], you can only create keys with these two scopes or a subset. - You cannot create a key with write:artifacts even though it exists in the system.

This ceiling is a trust boundary — escalation to full admin scope is required to grant broader scopes.

Audit Trail

Every API key mutation (create, scope change, revoke) is logged to a dedicated api_key_audit_log table with:

  • Timestamp — When the action occurred
  • Actor — The admin (or system) that performed the action
  • Action — created, scopes_updated, or revoked
  • Key label — The key's user-provided name
  • Scope delta — For scope changes, old and new values
  • User — The key's owner

You can view the audit trail in the SkillMeat web UI under Admin → Audit Events (filtered for API key events) or query it programmatically via the /api/v1/admin/audit-events endpoint.

Best Practices

  1. Label consistently — Use names that reflect the key's purpose: ci-pipeline, data-ingest-webhook, monitoring-bot.
  2. Minimize scopes — Grant only the scopes a key needs; avoid blanket admin:*.
  3. Set expiration — Use reasonable expiration windows (30–90 days) and rotate regularly.
  4. Monitor last-used — Revoke keys that are never used; they may represent forgotten credentials.
  5. Distribute keys securely — Use encrypted channels (not email or Slack) to share full keys with users.