Skip to content

API Key Management

Users can create and manage their own API keys through the web UI without admin intervention.

User Self-Service (Web UI)

Accessing the Account Page

Navigate to: http://your-server:8000/account/

Or from any page (once logged in), look for the "Profile" link in the Settings menu.

Creating an API Key

  1. Go to Account Page: Navigate to /account/
  2. Expand "Create New API Key" section
  3. Fill in the form:
  4. Name (required): A descriptive name like "N8N Workflow" or "CI/CD Pipeline"
  5. Description (optional): Additional details about the key's purpose
  6. Expiration (optional): Number of days until the key expires (1-3650 days, ~10 years)
  7. Click "Create API Key"
  8. IMPORTANT: Copy the generated API key immediately - it will never be shown again!

Viewing Your API Keys

The profile page shows a table of all your API keys with: - Name & Description - Key Prefix: First 8 characters for identification (e.g., sf_xxxxx...) - Status: Active (🟢) or Revoked (⚪) - Usage Stats: Request count and last used timestamp - Creation Date - Expiration Date (if set)

Revoking an API Key

  1. Find the key in the list
  2. Click the "Revoke" button
  3. Confirm the action
  4. The key will be immediately deactivated

Note: Revoking cannot be undone. Any applications using the key will lose access immediately.

API Key Scopes

API keys automatically inherit all scopes (permissions) from the user who created them.

Example: If your user account has these scopes: 

- presentations:generate
- presentations:read
- scraping:search
- scraping:scrape

Any API key you create will have the same scopes.

Full Access: If your account has the * (wildcard) scope, your API keys will also have full access to all endpoints.

Using Your API Key

Once created, use your API key in one of two ways:

Option 1: X-API-Key Header

curl -X POST http://localhost:8000/api/scraping/search \
  -H "X-API-Key: sf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI trends", "num_results": 5}'

Option 2: Authorization Bearer Header

curl -X POST http://localhost:8000/api/scraping/search \
  -H "Authorization: Bearer sf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI trends", "num_results": 5}'

N8N Credential Configuration

  1. In N8N, add a new Slidefactory API credential
  2. API URL: http://your-server:8000
  3. API Key: Paste your sf_xxxxx... key
  4. Save and test the connection

Admin CLI Tools

Admins can still use the CLI for advanced management:

Create API Key (Admin)

python -m cli api-key create \
  --user-id user@example.com \
  --user-email user@example.com \
  --scopes "*" \
  --description "Admin API key" \
  --expires-days 365 \
  "Admin Key"

List All API Keys

python -m cli api-key list

List User's API Keys

python -m cli api-key list --user-id user@example.com

Revoke API Key (Admin)

python -m cli api-key revoke 123

Where 123 is the key ID from the list command.

API Endpoints

For programmatic management (requires session authentication):

GET /account/me

Get current user's profile information.

curl -X GET http://localhost:8000/account/me \
  --cookie "session=your_session_cookie"

Response: 

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "scopes": ["*"],
  "auth_provider": "local"
}

GET /account/api-keys

List your API keys.

curl -X GET http://localhost:8000/account/api-keys \
  --cookie "session=your_session_cookie"

Response: 

[
  {
    "id": 1,
    "name": "My API Key",
    "key_prefix": "sf_xxxxx",
    "scopes": ["*"],
    "is_active": true,
    "usage_count": 42,
    "last_used_at": "2025-11-06T10:30:00Z",
    "created_at": "2025-11-01T08:00:00Z",
    "expires_at": "2026-11-01T08:00:00Z",
    "description": "For automated workflows"
  }
]

POST /account/api-keys

Create a new API key.

curl -X POST http://localhost:8000/account/api-keys \
  --cookie "session=your_session_cookie" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "description": "For automated workflows",
    "expires_days": 365
  }'

Response: 

{
  "id": 1,
  "api_key": "sf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "sf_xxxxx",
  "name": "My API Key",
  "scopes": ["*"],
  "expires_at": "2026-11-01T08:00:00Z",
  "message": "API key created successfully. Save it securely - it won't be shown again!"
}

IMPORTANT: Save the api_key value immediately. It won't be shown again!

DELETE /account/api-keys/{key_id}

Revoke an API key.

curl -X DELETE http://localhost:8000/account/api-keys/1 \
  --cookie "session=your_session_cookie"

Response: 

{
  "status": "success",
  "message": "API key 'My API Key' has been revoked",
  "key_id": 1,
  "key_prefix": "sf_xxxxx"
}

Security Best Practices

  1. Never share API keys - Each user should create their own keys
  2. Use descriptive names - Makes it easier to identify and manage keys
  3. Set expiration dates - Reduces risk if a key is compromised
  4. Revoke unused keys - Keep your key list clean
  5. Store keys securely - Use environment variables or secret managers
  6. Monitor usage - Check the "Usage" column to detect unexpected activity
  7. Rotate keys regularly - Create new keys and revoke old ones periodically

Troubleshooting

"Invalid API key" Error

  • Check that you copied the entire key (starts with sf_)
  • Verify the key hasn't been revoked
  • Check if the key has expired

"API key lacks required scope" Error

  • Your API key inherits your user account's scopes
  • Contact an admin to grant additional scopes to your user account
  • Create a new API key after your scopes are updated

Can't see the Account page

  • Ensure you're logged in (check for session cookie)
  • Try accessing /account/ directly
  • Check browser console for JavaScript errors

API key not working in N8N

  • Verify the API URL is correct (no trailing slash)
  • Check that your key has the required scopes for the operation
  • Test the key using curl first to isolate the issue

FAQ

Q: Can I have multiple API keys? A: Yes! Create as many as you need for different applications or purposes.

Q: Do API keys expire? A: Only if you set an expiration date during creation. Otherwise, they last indefinitely (or until revoked).

Q: Can I see a revoked key's value again? A: No, once created, the key value is never stored or displayed again. If you lose it, create a new one.

Q: What happens to applications using a revoked key? A: They will immediately receive "401 Unauthorized" errors. Update them with a new key.

Q: Can I edit an API key's name or description? A: Not currently. Create a new key and revoke the old one if needed.

Q: How do I grant different scopes to different keys? A: Currently, all your API keys inherit your account's scopes. For different permission levels, use separate user accounts.

Q: Can admins see my API keys? A: Admins can see API key metadata (name, prefix, usage) but never the actual key value. Only you see the full key when you create it.