API Keys & Authentication

Overview of the authentication methods supported by the Polycrate API: SSO/OIDC, user API keys, system and organization API keys, and agent tokens, including the permission model and security best practices.

API Keys & Authentication

Overview

The Polycrate API supports several authentication methods for different use cases:

SSO / OIDC

Supported providers

The Polycrate API supports OpenID Connect (OIDC) with:

• Keycloak (default)
• Azure AD / Entra ID
• Okta
• Google Workspace
• Other OIDC-compatible providers

Login flow

┌─────────┐      ┌─────────────┐      ┌──────────────┐
│ Browser │─────▶│ Polycrate   │─────▶│ SSO Provider │
│         │      │   API       │      │ (Keycloak)   │
└─────────┘      └─────────────┘      └──────────────┘
     │                  ▲                    │
     │                  │                    │
     │           ┌──────┴──────┐            │
     │           │   Session   │            │
     │           │   created   │            │
     │           └─────────────┘            │
     │                                       │
     └───────────────────────────────────────┘
              Redirect after login

Group mapping

OIDC groups can be mapped automatically to Polycrate roles:

The group names are configurable via environment variables (not hardcoded):

The group names in the table above are conventions – in practice, the value in the environment variable must match the actual Keycloak group names.

Setting up Keycloak OIDC

For SSO login, an OIDC client must be configured in Keycloak:

1. Create the client: Clients → Create client → Client ID (e.g. polycrate-api), Client authentication: ON (confidential), Standard flow: ON
2. Set redirect URIs: Valid redirect URIs: https://<polycrate-api-host>/*
3. Copy the client secret: Credentials tab → Client Secret
4. Create the groups scope: Client Scopes → Create → Name: groups, Mapper: Group Membership (Token Claim Name: groups, Full group path: OFF)
5. Assign the scope: Client → Client Scopes → Add groups as Default

The OIDC configuration is done via environment variables:

The scopes openid, email, profile and groups are requested automatically.

System API Keys

System API Keys are tokens for services that need global access to the Polycrate API – without a user context. A typical use case is a Customer Portal backend that manages resources on behalf of customers.

Permissions

• Full access like a Super Admin (all organizations, all resources)
• Optionally in read mode (read-only access)
• Can create, list and delete Organization API Keys

Creating a System API Key

1. Administration → System API Keys → + New
2. Assign a name and choose the access mode (read or read_write)
3. The token is shown exactly once – store it immediately

Usage

curl https://api.acme.corp/api/v1/organizations/ \
  -H "Authorization: Bearer <system-api-key-token>"

Organization API Keys

Organization API Keys are tokens with org scope for customers or third-party systems acting on behalf of a specific organization. They only see and manage resources of their own organization.

Permissions

• Access to all resources of the own organization (DNS zones, buckets, endpoints, backups, …)
• Optionally in read mode (read-only access)
• Can be created by System API Keys or administrators

Creating an Organization API Key

As an administrator (or via System API Key):

POST /api/v1/organizations/{org-name}/api-keys/
{
  "name": "customer-portal-prod",
  "access_mode": "read_write"
}

In the web UI: open the organization → API Keys tab → + New

The token is returned once in the response.

Usage

curl https://api.acme.corp/api/v1/domains/dnszones/ \
  -H "Authorization: Bearer <org-api-key-token>"

Access is automatically restricted to the own organization – cross-tenant access is rejected with 403.

User API Keys

What are User API keys?

User API keys are long-lived tokens for programmatic access as a signed-in user. They have the same permissions as the user who created them.

Creating a User API key

1. Open Profile → API Keys
2. Click + New API Key
3. Enter a name (e.g. "MacBook Pro", "CI/CD Pipeline")
4. Optional: set an expiry date
5. Important: the token is shown only once – copy it immediately!

Using the API key

=== "CLI configuration"

# ~/.polycrate/polycrate.yml
api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: poly_abc123def456...

=== "cURL"

curl -X GET https://hub.polycrate.io/api/v1/workspaces/ \
  -H "Authorization: Bearer poly_abc123def456..."

=== "Python"

import requests

headers = {
    "Authorization": "Bearer poly_abc123def456..."
}

response = requests.get(
    "https://hub.polycrate.io/api/v1/workspaces/",
    headers=headers
)

User API key properties

Revoking a User API key

1. Open Profile → API Keys
2. Find the key to revoke
3. Click Delete
4. Confirm the action

Agent Tokens

What are agent tokens?

Agent tokens are special tokens for Polycrate monitoring agents. They have restricted permissions:

• ✅ Fetch endpoints
• ✅ Report check results
• ✅ Update agent status
• ❌ Change configuration
• ❌ Access other resources

Creating an agent token

1. Open Monitoring → Agents
2. Click + New Agent
3. Enter a name and location
4. The agent token is generated

Using the agent token

polycrate api agent --agent-token "agt_xyz789..."

Permission Model

Role hierarchy

Super Admin
    │ All rights in the system
    │
    ▼
Org Admin
    │ All rights in one organization
    │
    ▼
Workspace Admin
    │ All rights in one workspace
    │
    ▼
User
    │ Read + write (restricted)
    │
    ▼
Viewer
    │ Read only

Default permissions

Security Best Practices

API key management

1. Separate keys per use case - One for local development - One for CI/CD - One per automation script

2. Set expiry dates - CI/CD keys: 90 days - Developer keys: 365 days - Temporary keys: 7 days

3. Regular rotation - Critical keys every 90 days - All keys at least annually

Secret storage

=== "Environment variables"

export POLYCRATE_API_KEY="poly_abc123..."
polycrate run my-block install

=== "Secret Manager"

# AWS Secrets Manager
export POLYCRATE_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id polycrate/api-key --query SecretString --output text)

=== "CI/CD Secrets"

# GitHub Actions
- name: Run Polycrate
  env:
    POLYCRATE_API_KEY: ${{ secrets.POLYCRATE_API_KEY }}
  run: polycrate run my-block deploy

Never do this

• ❌ Commit API keys to Git
• ❌ Print keys in logs
• ❌ Share keys in public channels
• ❌ Use one key for everything
• ❌ Use keys without an expiry date for CI/CD

Audit Logging

All authentication events are logged:

Logs can be viewed under Administration → Audit Logs.