API Keys

API keys authenticate every request to the oec.sh Public API. Keys are created in the oec.sh dashboard only. Listing and revoking keys also works through the Public API (see Managing Keys with the API), so a leaked key can be revoked from a script.

Requires Starter plan or higher. API key access is not available on the Free plan. Upgrade at Settings → Billing to enable the Public API.

Creating an API Key

Open Settings

In your oec.sh dashboard, go to Settings → API Keys.

Click "Create API Key"

Fill in the form:

Field	Description
Name	A label for this key. Use something descriptive like `github-actions-prod` or `monitoring-dashboard`.
Tier	`Read-only` or `Full access` — see Key Tiers below.
Scope	`Organization` or `Project` — see Key Scopes below.
Expiry	Optional. Leave blank for a non-expiring key.

Copy your key immediately

⚠️

The full key is shown only once. It is hashed before storage and cannot be retrieved again. Copy it to a secrets manager (GitHub Secrets, HashiCorp Vault, AWS Secrets Manager, 1Password) right now. If you lose it, revoke it and create a new one.

Your key will look like:

oec_live_rw_abc1def2ghi3jkl4mno5pqr6stu7vwx8yz90...   ← full access
oec_live_ro_xyz9wvu8tsr7qpo6nml5kji4hgf3edc2ba10...   ← read-only

Key Tiers

Tier	Prefix	What it can do
Read-only	`oec_live_ro_`	`GET` requests only — list projects, environments, statuses, logs, webhook deliveries.
Full access	`oec_live_rw_`	All operations — deploy, create, update, delete, manage webhooks.

Use read-only keys for monitoring dashboards, status checks, and audit tooling where write access would be a security risk.

Key Scopes

Scope	Access
Organization	All projects and environments owned by your organisation. Use for CI/CD pipelines that span multiple projects.
Project	A single named project only. All other projects return 404. Use for project-specific pipelines and least-privilege setups.

Project-scoped keys are recommended when you're giving a key to a third-party integration or a contractor who should only see one project.

Per-key Switches

Two powers are off on every new key and are turned on per key, next to the key under Settings → API Keys (organization admins only):

Switch	Field	Keys it can be turned on for	What it allows
Quick Connect	`can_register_servers`	Organization-scoped, full-access	Server registration tokens
Support tickets	`can_read_support_tickets`	Organization-scoped, any tier	Reading your organization's support tickets

Revoking a Key

Go to Settings → API Keys, find the key, and click Revoke.

⚠️

Revocation is immediate. Any service using the key will begin receiving 401 Unauthorized responses right away. Update your secrets before revoking a key that's in active use.

Managing Keys with the API

Two endpoints let an organization-scoped key list and revoke the organization's keys. There is no endpoint to create a key: a key that could create keys could give itself more access than it was granted, so creation stays in the dashboard.

Endpoint	Key needed	Result
`GET /org/api-keys`	Any organization-scoped key	`200` with the organization's active keys, newest first
`DELETE /org/api-keys/{key_id}`	Full-access, organization-scoped key	`204`; the key stops working immediately

A project-scoped key gets 403 with error org_scope_required on both, except on the revoke, where any read-only key (project-scoped or not) gets 403 with error read_only_key first. An unknown key id, or one from another organization, gets 404.

The list never contains the key itself, only its first characters (prefix):

[
  {
    "id": "8d6f0c2a-1b3e-4f5a-9c7d-2e4b6a8c0d1f",
    "name": "github-actions-prod",
    "prefix": "oec_live_rw_AbCd",
    "tier": "full_access",
    "scope": "org",
    "project_id": null,
    "is_active": true,
    "can_register_servers": false,
    "can_read_support_tickets": false,
    "last_used_at": "2026-10-05T09:12:44Z",
    "expires_at": null,
    "created_at": "2026-08-01T14:03:10Z"
  }
]

A key can revoke itself. That is deliberate: if a key has leaked, whoever holds it legitimately can shut it off at once without needing dashboard access.

curl -X DELETE https://api.oec.sh/api/public/v1/org/api-keys/$KEY_ID \
  -H "Authorization: Bearer oec_live_rw_your_key"

Key Naming Convention

We recommend naming keys to indicate their purpose and access level:

Example name	Tier	Scope	Purpose
`github-actions-prod`	full_access	org	GitHub Actions deploy workflow
`monitoring-dashboard`	read_only	org	Status dashboard polling
`staging-pipeline`	full_access	project	CI/CD for a single project
`slack-bot-readonly`	read_only	org	Slack `/status` command
`terraform-provider`	full_access	org	Infrastructure-as-code automation

Storing Keys Securely

Never put API keys in source code, .env files committed to git, or log output.

Recommended storage:

Platform	Where to store
GitHub Actions	Repository → Settings → Secrets → Actions secrets
GitLab CI	Project → Settings → CI/CD → Variables (masked)
Docker / Compose	Pass as env var at runtime, not in `docker-compose.yml`
HashiCorp Vault	`vault kv put secret/oecsh api_key=oec_live_rw_...`
AWS	Secrets Manager or Parameter Store (SecureString)
Kubernetes	`kubectl create secret generic oecsh --from-literal=api_key=...`

Audit Log

Every API key has an audit log showing the last 100 requests made with it — method, endpoint, status code, client IP, and timestamp. View it in Settings → API Keys → (key) → Audit Log.

Use the audit log to:

Confirm a CI/CD pipeline is calling the correct endpoints
Investigate unexpected usage or 4xx errors
Verify a key is actually being used before rotation

Key Expiry and Rotation

For security, consider setting an expiry date on long-lived keys and rotating them regularly:

Create a new key with the same tier and scope
Update your secrets store with the new key
Deploy your updated service
Verify the new key is working (check audit log)
Revoke the old key

If you suspect a key has been compromised, revoke it immediately — there is no delay.

Support Tickets & Release Notes MCP Server