Api keys

API keys provide long-lived, programmatic access to the S4E API. This page covers creating, managing, scoping, and revoking API keys.

Creating API Keys

Via the Web UI

  1. Navigate to Settings > API Keys.
  2. Click Create New Key.
  3. Enter a name, select scopes, and optionally set an expiration date.
  4. Click Create. The key is displayed once --- copy it immediately.

Via the API

curl -X POST "https://api.s4e.io/api/keys" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key",
    "scopes": ["read:assets", "read:findings", "write:scans"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Response:

{
  "data": {
    "id": "key-8a3b9c2d",
    "name": "CI/CD Pipeline Key",
    "key": "s4e_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "scopes": ["read:assets", "read:findings", "write:scans"],
    "created_at": "2026-04-28T12:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "last_used": null
  }
}

Warning

The key value is only returned in the creation response. It cannot be retrieved later. Store it securely immediately.

Key Scopes

Scopes control what an API key can access. Follow the principle of least privilege.

Scope Description
read:assets List and view assets.
write:assets Create, update, and delete assets.
read:scans List and view scan details and results.
write:scans Create, cancel, and configure scans.
read:findings List and view findings.
write:findings Update finding status and notes.
read:actions List and view action definitions.
write:actions Create and trigger actions.
read:playbooks List and view playbooks.
write:playbooks Create and run playbooks.
read:webhooks List webhook configurations.
write:webhooks Create and manage webhooks.
admin Full administrative access.

Scope Combinations

{
  "scopes": ["read:assets", "read:findings"]
}

A key with only read:* scopes cannot modify any resources. Use this for monitoring and reporting integrations.

Tip

Create separate keys for different use cases. A CI/CD key should have write:scans and read:findings, while a dashboard key needs only read:* scopes.

Listing API Keys

curl -X GET "https://api.s4e.io/api/keys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "key-8a3b9c2d",
      "name": "CI/CD Pipeline Key",
      "scopes": ["read:assets", "read:findings", "write:scans"],
      "created_at": "2026-04-28T12:00:00Z",
      "expires_at": "2027-01-01T00:00:00Z",
      "last_used": "2026-04-28T14:30:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

Note

The actual key value is never returned in list responses. Only the key metadata is visible.

Rotating Keys

To rotate a key, create a new key with the same scopes and then revoke the old one:

  1. Create a new key:
curl -X POST "https://api.s4e.io/api/keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key (rotated)",
    "scopes": ["read:assets", "read:findings", "write:scans"]
  }'
  1. Update your application to use the new key.
  2. Revoke the old key (see below).

Tip

Keep both keys active during the transition period to avoid downtime. Revoke the old key only after confirming the new key works.

Revoking Keys

curl -X DELETE "https://api.s4e.io/api/keys/key-8a3b9c2d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "message": "API key revoked."
}

Revocation is immediate. Any request using the revoked key will return 401 Unauthorized.

IP Allowlisting

Restrict an API key to specific IP addresses or CIDR ranges:

curl -X PUT "https://api.s4e.io/api/keys/key-8a3b9c2d" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_ips": ["203.0.113.0/24", "198.51.100.50"]
  }'

Requests from unlisted IPs will receive a 403 Forbidden response.

Rate Limit Tiers

API keys have rate limits based on their tier:

Tier Rate Limit Description
Standard 100 req/min Default for all keys.
Premium 1,000 req/min For high-volume integrations.
Enterprise 10,000 req/min Custom enterprise agreements.

See Rate Limits for detailed rate limiting behavior.

Key Management Best Practices

Practice Recommendation
Naming Use descriptive names indicating the key's purpose.
Scoping Grant the minimum scopes needed for the use case.
Expiration Set an expiration date; review and rotate regularly.
Storage Store keys in environment variables or secrets managers, never in code.
Rotation schedule Rotate keys at least every 90 days.
Monitoring Review last_used timestamps to find unused keys.
Separation Use different keys for different environments (dev, staging, prod).

Next Steps