Skip to content

API Keys

Use API keys for programmatic access to SkillMeat's API without interactive browser sign-in. Keys are personal tokens tied to your user account and inherit your roles and permissions.

Overview

API keys enable: - CI/CD pipelines — automated artifact deployment and management - Local scripts — programmatic access from your development environment - Third-party integrations — webhooks and automation platforms - Tooling — custom CLIs and SDKs

Each key is hashed at rest, can be revoked instantly, and optionally expires after a set period.

Creating an API Key

Via Web UI

  1. Navigate to Settings → API Keys
  2. Click Create Key
  3. Enter a descriptive name (e.g., "CI Pipeline" or "Local Development")
  4. (Optional) Set an expiration date; default is 90 days
  5. Click Create

The full key is displayed once. Copy and store it securely — you cannot view it again.

Via CLI

skillmeat auth api-key create "My Key Name" [--expires-in-days 90]

Output: 

Created API key: smk_live_abc12345_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Name: My Key Name
Expires: 2026-08-19

Store the key in an environment variable or .env file:

export SKILLMEAT_API_KEY="smk_live_abc12345_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Using an API Key

Via X-API-Key Header

curl -H "X-API-Key: smk_live_abc12345_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://skillmeat.example.com/api/v1/artifacts

Via Authorization Bearer Token

curl -H "Authorization: Bearer smk_live_abc12345_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://skillmeat.example.com/api/v1/artifacts

In Code

TypeScript/JavaScript: 

const response = await fetch('https://skillmeat.example.com/api/v1/artifacts', {
  headers: {
    'X-API-Key': process.env.SKILLMEAT_API_KEY
  }
});

Python: 

import os
import requests

headers = {
    'X-API-Key': os.environ.get('SKILLMEAT_API_KEY')
}
response = requests.get(
    'https://skillmeat.example.com/api/v1/artifacts',
    headers=headers
)

Listing Keys

Via Web UI

Navigate to Settings → API Keys to see all your keys, their creation dates, and last-used timestamps.

Via CLI

skillmeat auth api-key list

Output: 

Name              Created            Expires            Last Used
---               ---                ---                ---
CI Pipeline       2026-05-21         2026-08-19         2026-05-21
Local Dev         2026-04-15         2026-07-14         2026-05-20

Revoking a Key

Via Web UI

  1. Navigate to Settings → API Keys
  2. Find the key you want to revoke
  3. Click Revoke
  4. Confirm the action

Revocation is immediate — the key cannot be used in subsequent requests.

Via CLI

skillmeat auth api-key revoke "CI Pipeline"

Key Format & Security

API keys follow the format:

smk_{env}_{prefix8}_{secret32}

Where: - smk_ — SkillMeat key prefix - {env} — live or test (environment suffix) - {prefix8} — 8-character alphanumeric prefix for indexing - {secret32} — 32-character secret, hashed at rest using Argon2id

Security practices: - Never commit keys to version control; use environment variables - Rotate keys periodically (e.g., quarterly for production systems) - Revoke keys immediately if exposed - Use separate keys for each environment or integration - Restrict key permissions where possible (future enhancement)

Expiration & Limits

Default Behavior

  • Default TTL: 90 days
  • Maximum TTL: 365 days
  • Per-user key limit: 20 active keys
  • Soft-delete grace period: Revoked keys are soft-deleted (queries exclude them); hard-deleted after 90 days

Renewal

When a key expires, it stops authenticating. Create a new key and update your environment variables or configuration:

# Create a new key with the same name
skillmeat auth api-key create "CI Pipeline" --expires-in-days 90

# Revoke the old key
skillmeat auth api-key revoke "CI Pipeline (old)"

Multi-Worker Caveat

When multiple workers or processes use the same API key simultaneously, last_used_at updates are debounced (coalesced) to reduce database contention:

  • Debounce window: 60 seconds (configurable via api_keys_debounce_seconds)
  • Behavior: The timestamp reflects the most recent request within the window, but intermediate requests are not individually logged

If you need precise per-request audit trails, use separate keys per worker or enable audit logging for your deployment.

Troubleshooting

"Invalid API key" - Verify the full key is copied correctly (spaces, line breaks) - Check the key hasn't expired - Confirm the key hasn't been revoked - Ensure the key is being passed via X-API-Key header or Authorization: Bearer token

"Missing API key" - Add the key to the X-API-Key header or Authorization: Bearer header - Ensure environment variables are set correctly

"Unauthorized" - Your API key is valid, but you lack permission for the requested operation - Verify your SkillMeat roles and scopes match the endpoint requirements - Contact your SkillMeat administrator

Next Steps