Authentication

All requests to the oec.sh Public API must include an API key. Keys are created per organization and can be scoped to a single project.

Key Types

Type	Prefix	Rate Limit	Use for
Read-only	`oec_live_ro_`	120 req/min	Monitoring, dashboards, status checks
Full access	`oec_live_rw_`	20 req/min	Deployments, CI/CD, automation

Read-only keys can only call GET endpoints. Attempting a POST, PUT, PATCH, or DELETE with a read-only key returns 403 Forbidden.

Key Scopes

Scope	Access
Organization	All projects and environments in the organization
Project	Only resources belonging to a single project

Use project-scoped keys when you want to give a specific pipeline or integration access to exactly one project — nothing else.

Creating a Key

Open API Key Settings

Log in to the oec.sh platform
Go to Settings (top-right or sidebar)
Click the API Keys tab

Create the Key

Click Create Key
Give it a descriptive name (e.g., github-actions-staging, terraform-prod)
Choose Key type: Read-only or Full access
Choose Scope: Organization or Project (select the project if project-scoped)
Optionally set an Expiry date — keys without an expiry are valid indefinitely
Click Create

Copy the Key

⚠️

The full key value is shown only once, immediately after creation. Copy it now and store it securely. After you close this dialog, only the key prefix is visible and the key cannot be retrieved — only revoked.

Your key looks like:

oec_live_rw_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using Your Key

Authorization Header (Recommended)

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer oec_live_rw_your_key_here

X-API-Key Header (Alternative)

You can also pass it in the X-API-Key header:

X-API-Key: oec_live_rw_your_key_here

Both headers are equivalent. If both are present, Authorization takes precedence.

Code Examples

# Authorization header
curl https://api.oec.sh/api/public/v1/projects \
  -H "Authorization: Bearer oec_live_rw_your_key_here"
 
# X-API-Key header (equivalent)
curl https://api.oec.sh/api/public/v1/projects \
  -H "X-API-Key: oec_live_rw_your_key_here"

Key Security

⚠️

Never commit API keys to source code. Use environment variables or a secrets manager.

Best practices:

GitHub Actions — Store in Settings → Secrets → Actions, reference as ${{ secrets.OEC_API_KEY }}
GitLab CI — Store in Settings → CI/CD → Variables, reference as $OEC_API_KEY
HashiCorp Vault — Store at a secret/oec-api-key path, inject at runtime
AWS Secrets Manager / GCP Secret Manager — Store and retrieve via SDK
Docker / Kubernetes — Pass as an environment variable or mounted secret

If a key is compromised, revoke it immediately in Settings → API Keys and create a new one.

Key Expiry

Keys can be created with an optional expiry date. When a key expires:

All requests using that key return 401 Unauthorized with error code key_expired
The key appears as Expired in the API Keys list and can be deleted

For long-lived integrations (CI/CD, Terraform), either use a key without expiry or set a calendar reminder to rotate it before it expires.

Checking Which Key Was Used

Every API response includes the X-API-Key-Id header with the key's short ID. This helps correlate requests to the key in your audit log:

X-API-Key-Id: key_01abc...

Overview Rate Limits