Organization API keys give your automation, CI pipelines, and third-party integrations a durable, scoped credential for programmatic access to the platform. You issue a key from your organization settings, assign it the minimum set of permissions it needs, and use it in the Authorization: Bearer header — without sharing your personal session token or granting broader access than the integration actually requires. API keys complement the user-facing access model described in RBAC and custom roles for AI operations, adding a purpose-built credential path for non-human callers.

Why One All-Powerful Token Is a Liability

The simplest approach to API access is one root credential that can do everything. Teams adopt it because it is quick to set up, but it creates a fragile posture. If that credential leaks — through a misconfigured CI environment variable, an over-broad log line, or a third-party integration — the blast radius covers your entire organization. Revocation requires replacing every integration at once, which means the credential rarely gets rotated at all.

Scoped keys solve this by narrowing what each credential can do. An analytics export job needs read access to usage data. A deployment pipeline that registers agents needs write access to agent configuration. A SIEM forwarder needs read access to audit logs. None of these needs the other's permissions. When each integration gets its own key with only the scopes it requires, a compromise of one key affects only what that key can reach. For a fuller treatment of the least-privilege principle applied to agent callers, see How to Implement Least Privilege for AI Agents.

How API Keys Work in Praesidia

Organization API keys are long-lived credentials issued at the organization level, distinct from user session tokens. They are designed for server-to-server and automation use cases where a human login flow would be inappropriate.

When you create a key, the platform generates a high-entropy token with a recognizable prefix so you can identify it on sight in logs and configuration. The raw key value is shown exactly once — at creation — and is not recoverable afterward. Only a cryptographic hash is retained for verification, which means a database read cannot yield usable credentials even in a worst-case scenario.

After creation, you copy the key into your integration — an environment variable in your CI system, a secret in your deployment platform, or a configuration entry in your data pipeline. From that point forward, every API request authenticated with that key is scoped to your organization and constrained by the scopes you assigned.

Assigning Scopes

When you create a key, you assign it a set of scopes that determine which API capabilities it can exercise. Scopes map to permission categories: viewing agents and their status, managing workflow configuration, reading audit logs, accessing analytics and cost data, and so on.

The intent is to match the scope set to the actual use of the integration. An integration that reads cost and usage data for a finance dashboard does not need write access to agent configuration, and assigning that write access is a residual risk with no benefit. Reviewing scope assignments periodically — especially when an integration changes purpose — is the same hygiene you would apply to any IAM policy.

Praesidia's permission model applies a unified access control layer to both API key-authenticated requests and human user sessions. There is no separate access model to maintain for API consumers versus logged-in users — the same access decisions apply regardless of how the caller authenticated.

Listing and Revoking Keys

The API keys management surface, under Configure → Integrations → API Keys, shows you every active key in the organization: its name, the prefix that lets you identify it, the scopes assigned, when it was created, and when it was last used. You can filter and sort to find the key you are looking for without exposing the underlying token.

Revocation is immediate and soft: the key is stamped with a revocation timestamp and reason, and all subsequent requests authenticated with that key receive a 401. The revocation record is retained in the audit trail so you have a history of which key was revoked, when, and by whom. This matters for compliance reviews and incident retrospectives where you need to show that a credential was withdrawn promptly after a suspected exposure.

You can revoke keys individually or in bulk. If you discover a class of integrations using keys that should be replaced — for example, after a rotation policy deadline — bulk revocation lets you cut them all in one action rather than working through them one by one.

Key Rotation

Rotating an API key means replacing a credential on a schedule or after an event without interrupting the integrations that depend on it. The recommended pattern is to create the new key, update the consuming integration to use it, verify the integration is working on the new credential, and then revoke the old one. This overlapping window avoids downtime while ensuring the old credential is not retained longer than necessary.

The platform's audit log records key creation and revocation events, giving you a trail that confirms rotation happened and when. Teams operating under compliance frameworks that mandate credential rotation intervals can use this trail to demonstrate adherence. For a broader look at what audit records should contain and how to make them hold up under scrutiny, see audit trails that hold up.

Gating Access with Feature Flags

API key management in Praesidia is available on plans that include programmatic access. If your plan does not include this capability, the API Keys section of the integration settings will reflect that, and attempts to create keys through the API will return an appropriate error rather than silently failing.

This plan-level gating means teams can evaluate the platform without necessarily granting programmatic access to the organization, and administrators can expand access as the use case matures.

What Gets Logged

Every API key operation — creation, access, revocation — is recorded in the organization's audit log with the actor, timestamp, key prefix, and the action taken. Requests made with an API key include the key's identifier in the audit event, so you can trace which credential performed a given action in a compliance review or incident investigation.

This traceability is the reason API keys are preferable to shared user credentials for automation. When a workflow registers an agent at 03:00 on a Sunday, the audit log shows the key identifier rather than a human user's account, making the action legible and attributable without creating confusion about whether a person was involved. For guidance on forwarding these audit events to a SIEM or external system, see Webhooks and SIEM Forwarding.

Common questions

How many keys can an organization have? There is no fixed upper limit on the number of keys per organization. The practical recommendation is to issue one key per integration rather than sharing a key across multiple consumers. This gives each integration its own revocation surface and makes audit trails unambiguous.

What happens to in-flight requests when a key is revoked? Revocation takes effect immediately. Any request that arrives after the revocation timestamp — even if it was initiated a fraction of a second before — will be rejected with a 401. There is no grace period. This is intentional: a key revoked because of suspected exposure should stop working as quickly as possible.

Can I use an API key alongside SSO? Yes. API keys and SSO serve different access patterns. SSO governs how human users authenticate to the dashboard; API keys govern how automation and integrations authenticate to the REST API. Both can be active in the same organization simultaneously. See single sign-on for AI agent management for details on how SSO and programmatic credential types coexist.

How do API keys relate to webhook security? API keys authenticate outbound calls your integrations make to the platform. Webhooks run in the opposite direction — the platform calls your endpoint. Those outbound events should be signed so your endpoint can verify they originated from a legitimate source. See webhook security: signing and verifying events for the complementary pattern.