API Keys

API keys provide programmatic access to the oCore API without requiring interactive authentication. They are ideal for CI/CD pipelines, automation scripts, and third-party integrations. Each API key is scoped to an organization and can be configured with specific permissions.

Creating an API Key

curl -X POST https://ocore.example.com/api/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "permissions": ["manage:instances", "view:servers"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

ocore api-key create \
  --name "CI/CD Pipeline" \
  --permissions manage:instances,view:servers

Using API Keys

Authentication Header

Include the API key in the Authorization header with a Bearer prefix:

curl https://ocore.example.com/api/servers \
  -H "Authorization: Bearer ocore_key_abc123..."

API Key vs JWT Token

Organization Context

API keys are scoped to a specific organization. The organization context is automatically set based on the key -- you do not need to provide an organization header or parameter.

Managing API Keys

Listing Keys

curl https://ocore.example.com/api/api-keys \
  -H "Authorization: Bearer $TOKEN"

Each key entry shows:

• Name and description
• Created date
• Last used date
• Expiration date
• Permission summary
• Status (active, expired, revoked)

Revoking a Key

Immediately revoke an API key to prevent further use:

curl -X DELETE https://ocore.example.com/api/api-keys/{keyId} \
  -H "Authorization: Bearer $TOKEN"

ocore api-key revoke <key-id>

Revocation is immediate -- any in-flight requests using the key will fail with 401 Unauthorized.

Best Practices

Key Rotation

Regularly rotate API keys to limit the impact of potential key exposure:

Least Privilege

Grant only the permissions each key actually needs:

Security Guidelines

• Never commit API keys to version control
• Use environment variables or secret managers to store keys
• Set expiration dates on keys used for temporary integrations
• Monitor the "last used" date -- revoke unused keys
• Use separate keys for separate integrations (do not share keys)
• Enable audit logging to track API key usage

Required Permissions

OAuth-Created API Keys

When users connect an AI client (Claude Desktop, ChatGPT) through the OAuth consent flow, oCore automatically creates an API key linked to the resulting OAuth token. These keys are flagged with mcp_only: true and exist solely to back MCP sessions -- they cannot be used for general API access.

How OAuth Consent Creates API Keys

During the OAuth consent flow, the user can either:

• Auto-create a new key: oCore generates a new mcp_only API key scoped to the selected organization. The key name defaults to the OAuth client's name (e.g., "Claude Desktop").
• Link an existing key: If the user already has MCP API keys in the selected organization, the consent form offers a picker to reuse one. No new key is created.

The auto-created key inherits its MCP permissions from the OAuth scopes and the user's consent form selections.

Permission Configuration During OAuth Consent

The consent form gives users fine-grained control over what the connected AI client can do:

These settings are stored on the authorization code and applied to the auto-created API key when the code is exchanged for tokens.

How MCP Tools Are Filtered

When an OAuth-backed MCP session starts, tools are filtered based on the linked API key's permissions:

1. The OAuth access token is resolved to its linked API key.
2. The key's mcp_permissions list determines which tool categories are available.
3. The key's mcp_allowlist_mode and mcp_tool_allowlist further filter individual tools.
4. The key's mcp_instance_ids restricts which instances appear in the session.
5. If mcp_read_only is set, all write and destructive tools are removed.

An empty permissions list means unrestricted access to all categories, identical to manually-created keys.

Revoking OAuth Authorizations

When an OAuth token is revoked (via POST /oauth/revoke or from the dashboard), the auto-created API key is cleaned up:

• If the key was auto-created (auto_created_key: true) and no other active OAuth tokens reference it, the key is soft-deleted.
• If the user linked an existing key during consent, the key is left untouched since it existed before the OAuth flow.
• Revoking all tokens for a client effectively disconnects that AI tool from oCore.

Organization-level logout can also revoke all OAuth tokens for a user across the organization, cleaning up any auto-created keys that are no longer referenced.

Troubleshooting

API key returns 401 Unauthorized

• Verify the key value is correct (check for trailing whitespace)
• Check that the key has not been revoked
• Check that the key has not expired
• Ensure the Authorization: Bearer prefix is included

API key returns 403 Forbidden

• The key does not have the required permission for the requested endpoint
• Create a new key with the necessary permissions or update the existing one

Cannot find the key value

• API key values are shown only once at creation time
• If you lost the key, create a new one and revoke the old one
• Store new keys in a secure location immediately after creation

Key shows "expired" status

• Create a new key with the same permissions
• Set a longer or no expiration for keys used in long-running integrations
• Consider using key rotation schedules rather than fixed expiration dates