API Keys

API keys provide non-interactive authentication for automation workflows. Use them in CI/CD pipelines, Terraform providers, scripts, and third-party integrations without requiring an OAuth login flow.

Overview

API keys are org-scoped credentials that authenticate requests to the DAAM REST API. Each key is granted a specific set of scopes that determine which endpoints it can access, following the principle of least privilege.

• Scoped access — each key has a set of scopes that limit which API operations it can perform.
• IP allowlisting — optionally restrict key usage to specific IP addresses or CIDR ranges.
• Expiration — keys can have an optional expiration date for time-limited access.
• Audited — all API key operations (creation, revocation, authentication) are recorded in the audit log.
• Non-interactive — no browser-based OAuth flow required; include the key in the Authorization header.

Creating an API Key

Org admins can create API keys from the console or via the REST API.

Via the Console

1. Navigate to Settings in the sidebar, then click API Keys.
2. Click Create API Key.
3. Enter a key Name (alphanumeric, hyphens, and underscores; 1-64 characters).
4. Select Scopes using individual checkboxes or the quick-select buttons (Admin or Read-only).
5. Optionally set an Expiration Date. We recommend setting an expiration for security best practices.
6. Optionally add IP Allowlist entries (CIDR notation, one per line).
7. Click Create API Key.

Via the REST API

curl -X POST https://your-daam-instance/api/v1/api-keys \
  -H "Authorization: Bearer daam_YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "scopes": ["policies:read", "databases:read"],
    "expires_at": "2026-12-31T23:59:59Z",
    "allowed_cidrs": ["10.0.0.0/8"]
  }'

The response includes the raw key in the raw_key field. This is the only time the full key is returned.

Authentication

Include the API key in the Authorization header as a Bearer token:

Authorization: Bearer daam_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdef

API keys are identified by the daam_ prefix. The server uses this prefix to distinguish API key tokens from JWT access tokens and routes them through the appropriate authentication path.

Scopes Reference

Every API key must have at least one scope. Scopes follow a resource:action pattern. When a request requires a scope the key does not have, the server returns 403 Forbidden.

Scope Aliases

Two convenience aliases are available when creating keys:

Aliases are expanded at creation time. The stored key contains only concrete scope values.

IP Allowlisting

Restrict API key usage to specific IP addresses or CIDR ranges. When an allowlist is configured, requests from IPs outside the allowlist are rejected with 401.

• No allowlist — the key can be used from any IP address.
• With allowlist — only requests from matching IPs are accepted.
• Both IPv4 and IPv6 CIDRs are supported.
• Single IPs can use /32 (IPv4) or /128 (IPv6) notation.
• Maximum 50 CIDR entries per key.

Example CIDR entries:

10.0.0.0/8
192.168.1.100/32
2001:db8::/32

Expiration and Revocation

API keys have three possible states:

• Expiration is optional. Keys without an expiration date remain active until manually revoked.
• Revocation is immediate and permanent. Revoked keys cannot be reactivated.
• Key creators receive email notifications 7 days before expiration and upon expiration.
• When an organization is deleted, all its API keys are automatically revoked.

To revoke a key via the console, navigate to the key detail page and click Revoke Key. To revoke via the API:

curl -X DELETE https://your-daam-instance/api/v1/api-keys/{key-id} \
  -H "Authorization: Bearer daam_YOUR_KEY"

Example API Calls

List Databases

curl https://your-daam-instance/api/v1/databases \
  -H "Authorization: Bearer daam_YOUR_KEY"

List Policies

curl https://your-daam-instance/api/v1/policies \
  -H "Authorization: Bearer daam_YOUR_KEY"

List Organization Members

curl https://your-daam-instance/api/v1/org/members \
  -H "Authorization: Bearer daam_YOUR_KEY"

List API Keys

curl "https://your-daam-instance/api/v1/api-keys?status=active" \
  -H "Authorization: Bearer daam_YOUR_KEY"

Create an API Key

curl -X POST https://your-daam-instance/api/v1/api-keys \
  -H "Authorization: Bearer daam_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "terraform-provider",
    "scopes": ["policies:read", "policies:write", "databases:read"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Revoke an API Key

curl -X DELETE https://your-daam-instance/api/v1/api-keys/{key-id} \
  -H "Authorization: Bearer daam_YOUR_KEY"

Security Best Practices

• Set expiration dates — use time-limited keys and rotate them regularly.
• Use minimal scopes — grant only the scopes required for the integration.
• Configure IP allowlists — restrict key usage to known CI/CD runner IPs or office networks.
• Store keys securely — use your CI/CD platform's secret management (e.g. GitHub Secrets, Vault).
• Revoke unused keys — regularly audit active keys and revoke any that are no longer needed.
• Monitor the audit log — review API key activity in the audit log for unexpected access patterns.