Skip to main content

​
Overview

API keys let you access the Alfred API from scripts, automations, and integrations. Each key provides full access to your API endpoints.

​
Creating an API key

  1. Go to your Alfred Black dashboard
  2. Navigate to Settings > API Keys
  3. Click Create
  4. Give it a descriptive name (e.g., “CI pipeline”, “n8n automation”, “shell scripts”)
  5. Click Create and copy the key immediately
Your API key is shown only once. Copy it immediately and store it somewhere safe. If you lose it, you’ll need to create a new one.

​
Key format

Alfred API keys use the format: 
alf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
The alf_ prefix followed by 32 hexadecimal characters.

​
Making API requests

Include your key in the Authorization header as a Bearer token: 
curl /api/v1/vault/context \
  -H "Authorization: Bearer alf_your_key_here"
All API endpoints use the base path /api/v1/....

​
Managing your keys

From the Settings > API Keys page in your dashboard, you can:
  • View all keys — See names, creation dates, and last used timestamps
  • Track usage — Check when each key was last used
  • Revoke keys — Delete keys you no longer need
You can create up to 10 API keys per account.

​
Best practices

  • Don’t hardcode keys — Use environment variables instead: 
    export ALFRED_API_KEY="alf_your_key_here"
curl /api/v1/vault/context -H "Authorization: Bearer $ALFRED_API_KEY"
  • Use descriptive names — Name keys after their purpose so you know which to revoke
  • Rotate periodically — Create a new key and revoke the old one every few months
  • Revoke unused keys — If you’re no longer using an integration, revoke its key

​
Example integrations

​
Shell script

#!/bin/bash
ALFRED_API_KEY="${ALFRED_API_KEY:?Set ALFRED_API_KEY}"

# Share content with Alfred
curl -X POST /api/v1/vault/inbox \
  -H "Authorization: Bearer $ALFRED_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"$(date +%Y-%m-%d)-notes.md\", \"content\": \"$1\"}"

​
Python automation

import os
import requests

API_KEY = os.environ['ALFRED_API_KEY']
HEADERS = {'Authorization': f'Bearer {API_KEY}'}

# Check vault status
response = requests.get('/api/v1/vault/context', headers=HEADERS)
print(response.json())

​
Error responses

If your key is missing or invalid, you’ll receive a 401 Unauthorized response: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or malformed Authorization header"
  }
}

​
Testing your key

Use the health endpoint to verify your key works: 
curl /api/v1/admin/health \
  -H "Authorization: Bearer alf_your_key_here"
A successful response confirms your API key is valid and your Alfred is reachable.

API Reference

See all available endpoints

Authentication

Full authentication documentation