Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Managing Developer API Keys

API keys provide authenticated access to your Shaf workspace data without exposing personal account credentials. Keys are scoped to specific permission levels and can be rotated without downtime.
Treat API keys like passwords. Never expose them in client-side code, commit them to version control, or share them in plaintext. Use environment variables or a secret manager.

Key Permissions Overview

Full Access
Read and write capabilities across all workspace resources:
  • Create, edit, delete links
  • Manage custom domains
  • Read and export analytics
  • Manage webhook endpoints
  • List and manage API keys
Read Only
Query-only access — ideal for analytics dashboards, monitoring scripts, and reporting pipelines:
  • List and get links
  • Read click analytics
  • Check domain verification status
Cannot create, modify, or delete any resources.

Creating an API Key

    Open API Key Settings

    Navigate to Settings → API Keys in the Shaf dashboard sidebar.

    Click Create API Key

    Click the + Create API Key button in the top-right.

    Configure the Key

    FieldDescriptionExample
    LabelHuman-readable name for this keyZapier Integration, Reporting Dashboard
    Permission ScopeWhat the key can accessFull Access or Read Only
    ExpirationWhen the key auto-revokes30 days, 90 days, 1 year, Never

    Copy Your Key Immediately

    Click Generate Key. The secret key is shown once in full. Copy it immediately and store it securely.
    After you navigate away from this screen, the full key cannot be retrieved again. If lost, you must generate a new key and revoke the old one.

Authenticating API Requests

Include the API key in the Authorization header as a Bearer token:
curl -X GET "https://api.shaf.app/v1/links" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json"
All API requests must use HTTPS. Plain HTTP requests are rejected at the edge.

Rotating a Key (Zero-Downtime)

    Create the New Key

    Follow the steps above to create a replacement key with the same permission scope.

    Update Your Application

    Replace the old secret in your application environment variable, secret manager, or CI/CD configuration:
    # Example: updating GitHub Actions secret via CLI
gh secret set SHAF_API_KEY --body "sk_live_new_key_here"

    Verify Requests Succeed

    Run a test request with the new key and confirm it returns expected results.

    Revoke the Old Key

    Return to Settings → API Keys and click Revoke next to the old key. The old key immediately stops authenticating requests.

Security Best Practices

Use a Secret Manager
Store keys in dedicated secret managers: HashiCorp Vault, Doppler, AWS Secrets Manager, GitHub Secrets, or Cloudflare Secrets.
Isolate Environments
Create separate keys for staging and production. This ensures audit logs are attributed correctly and a compromised staging key can't impact production.
Set Expiration Policies
Prefer short-lived keys (30–90 days) over Never for keys used in automated systems. Scheduled rotation reduces blast radius from key leaks.
Monitor Usage
Review the Last Used timestamp in the API Keys table regularly. Keys that haven't been used in 90+ days should be audited and potentially revoked.

Troubleshooting

I'm getting 401 Unauthorized errors
Verify the key is being passed in the Authorization: Bearer <key> header format with a space before the key and no extra quotes. Also confirm the key hasn't expired by checking the Expiration column in Settings → API Keys.
My Read Only key is returning a 403 Forbidden error on a write operation
Read Only keys cannot create, update, or delete resources. If you need write access, generate a new Full Access key.
How many API keys can I create?
Each workspace can have up to 25 active API keys simultaneously across all plans. Revoking a key frees up a slot.