API keys

API keys authenticate agents, integrations, and programmatic access to the Planekeeper API. Each key is scoped to an organization and grants access to that organization’s resources.

Key format

API keys follow this format:

pk_<id>_<secret>

Example: pk_42_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Creating API keys

1. Navigate to API Keys in the sidebar
2. Click Create API Key
3. Enter a descriptive name (for example, production-agent or ci-integration)
4. Click Create
5. Copy the displayed key immediately – it will not be shown again

The new key is active immediately and scoped to your current organization.

How agents use API keys

Agents authenticate every request to the Planekeeper API using the X-API-Key header:

X-API-Key: pk_42_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The agent sends this header with every heartbeat, task poll, and task completion request. The API server validates the key and derives the organization context from the key’s database record.

Server agent auto-provisioning

The server agent (deployed alongside the API server in the same Docker network) can automatically provision its own API key when the AGENT_API_KEY environment variable is not set. It creates a key named serveragent-auto-<hostname> with a 30-day TTL and deactivates the key on graceful shutdown.

For client agents deployed at remote sites, provide the API key via the AGENT_API_KEY environment variable.

Key scoping and permissions

Organization-scoped keys

Standard API keys are scoped to a single organization. They can:

• Create, read, update, and trigger jobs within the organization
• Create and manage rules, alert configs, and alerts
• Manage notification channels and rules
• Read upstream releases and version snapshots

System keys

System keys have no organization scope (organization_id is NULL). They can:

• Create global resources shared across all organizations
• Access cross-organization data
• Manage system-level settings

System keys are used by internal services and are not created through the standard UI.

Best practices

Use separate keys per agent

Create a unique API key for each agent deployment. This provides:

• Auditability – trace actions back to a specific agent
• Revocation – deactivate a single compromised key without affecting other agents
• Identification – see which agents are active in the service health page

Name keys descriptively

Use names that identify the purpose and location:

Rotate keys regularly

Periodically create new keys and deactivate old ones:

1. Create a new API key
2. Update the agent configuration with the new key
3. Verify the agent connects successfully with the new key
4. Deactivate the old key

Protect keys in transit and at rest

• Pass keys via environment variables, not command-line arguments (which appear in process listings)
• Store keys in a secrets manager (HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets)
• Never commit keys to version control
• Use encrypted connections (HTTPS) between agents and the API server

Deactivate unused keys

Review your API keys periodically and deactivate any that are no longer in use. Orphaned keys are an unnecessary security risk.

Troubleshooting

Agent returns 401 Unauthorized

• Verify the key is correct and complete (including the pk_ prefix)
• Check that the key has not been deactivated
• Confirm the agent is sending the key in the X-API-Key header
• Ensure the API server URL is correct (the agent must reach the server to validate the key)

Key was lost or forgotten

There is no way to recover a lost API key. Create a new key and update your agent configuration, then deactivate the old key.

Multiple agents using the same key

While this works technically, it prevents you from distinguishing between agents in logs and health checks. Create separate keys for each agent.