API Keys

API keys authenticate every request to the oec.sh Public API. They are created and managed from the oec.sh dashboard — there is no programmatic endpoint for key management in the Public API itself.

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.

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.

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.

Webhooks