API Keys

Manage API keys for authenticated account workflows.

Endpoints

Method	Endpoint	Description
GET	`/v1/api-keys`	List API keys
POST	`/v1/api-keys`	Create a new API key
DELETE	`/v1/api-keys/:id`	Revoke an API key
POST	`/v1/api-keys/:id/roll`	Roll a key

List Keys

curl "https://api.oilpriceapi.com/v1/api-keys" \
  -H "Authorization: Token YOUR_API_KEY"

{
  "status": "success",
  "data": [
    {
      "id": "key_123",
      "name": "Production",
      "prefix": "opa_live_",
      "last_used_at": "2026-07-15T14:30:00Z",
      "created_at": "2026-06-01T10:00:00Z"
    }
  ]
}

Create Key

curl -X POST "https://api.oilpriceapi.com/v1/api-keys" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Staging"}'

New keys are shown once. Store them immediately in your secret manager.

Roll Key

curl -X POST "https://api.oilpriceapi.com/v1/api-keys/key_123/roll" \
  -H "Authorization: Token YOUR_API_KEY"

Rolling creates a replacement secret for the selected key. Treat the old secret as revoked unless your account has an explicitly configured grace window.

Delete Key

curl -X DELETE "https://api.oilpriceapi.com/v1/api-keys/key_123" \
  -H "Authorization: Token YOUR_API_KEY"

Security Checklist

Use separate keys per environment.
Never expose keys in frontend JavaScript.
Rotate keys on a regular schedule and after staff/vendor changes.
Monitor /v1/account and usage dashboards after every roll.

Error Cases

Status	When
`401`	Missing or invalid API key
`403`	Key management is not allowed for this account
`404`	Key id not found
`422`	Name or request body invalid