API Keys

Name: notfs
Rating: 4.8 (50 reviews)
Author: notfs

Create and manage API keys for programmatic access.

API keys let you authenticate with the notfs API without using JWT tokens. Each key has scopes that control what it can access. Create keys from the iOS app (Settings > API Keys) or via the API.

Scopes

Scope	Allows
notifications:read	List and view notifications, stats
notifications:write	Create and cancel notifications
devices:read	List registered devices
devices:write	Register and remove devices

Create API Key

POST /api/keys

curl -X POST https://api.notfs.dev/api/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["notifications:read", "notifications:write"],
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

// Response (201)

{
  "id": "clx...",
  "name": "CI/CD Pipeline",
  "key": "ntfs_abc123def456ghi789...",
  "keyPrefix": "ntfs_abc123d",
  "scopes": ["notifications:read", "notifications:write"],
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "createdAt": "..."
}

⚠️ The full key value is only returned on creation. Store it securely — it cannot be retrieved later.

List API Keys

GET /api/keys

curl https://api.notfs.dev/api/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

// Returns array of keys (masked, showing only prefix)
[
  {
    "id": "clx...",
    "name": "CI/CD Pipeline",
    "keyPrefix": "ntfs_abc123d",
    "scopes": ["notifications:read", "notifications:write"],
    "isActive": true,
    "lastUsedAt": "2026-02-15T10:30:00.000Z",
    "createdAt": "..."
  }
]

Revoke API Key

DELETE /api/keys/:id

curl -X DELETE https://api.notfs.dev/api/keys/clx... \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

// { "success": true, "id": "clx..." }

Using API Keys

Include the key in the X-API-Key header:

curl https://api.notfs.dev/api/notifications \
  -H "X-API-Key: ntfs_your_key_here"

If the key lacks the required scope, you'll get a 401 error with the message "API key missing required scope: ...".