Opus 4.8 Best Practices

import os
import requests

BASE_URL = "https://api.opus.example.com"  # Opus 4.8 API base URL
API_KEY = os.environ["OPUS_API_KEY"]        # Store in a secret manager, not in source control

def opus_request(method, path, scopes=None, json_body=None):
    # Authentication: ApiKey scheme in Authorization header
    headers = {
        "Authorization": f"ApiKey {API_KEY}",
        "Content-Type": "application/json",
    }
    url = f"{BASE_URL}{path}"
    resp = requests.request(method, url, headers=headers, json=json_body, timeout=20)

    # Fail closed on auth errors and scope mismatches
    if resp.status_code in (401, 403):
        raise RuntimeError(f"Auth failed: {resp.status_code} {resp.text}")
    resp.raise_for_status()
    return resp.json()

# Admin-only: create a least-privilege key with explicit scopes and expiry
admin_key = os.environ["OPUS_ADMIN_API_KEY"]  # Separate admin credential; do not reuse app keys

admin_headers = {
    "Authorization": f"ApiKey {admin_key}",
    "Content-Type": "application/json",
}

create_payload = {
    "name": "backend-service-prod",
    "scopes": ["opus.read", "opus.write"],  # least privilege for this service
    "expires_at": "2026-10-01T00:00:00Z",
}

r = requests.post(
    f"{BASE_URL}/v1/api-keys",
    headers=admin_headers,
    json=create_payload,
    timeout=20
)
r.raise_for_status()
key_info = r.json()  # Expect fields like { "id": "...", "key": "..." , ... }

# Rotation with overlap: deploy new key first, then revoke old after verification
rotate_payload = {"rollover_strategy": "overlap", "reason": "Scheduled rotation"}
old_key_id = key_info["id"]

rot = requests.post(
    f"{BASE_URL}/v1/api-keys/{old_key_id}/rotate",
    headers=admin_headers,
    json=rotate_payload,
    timeout=20
)
rot.raise_for_status()
new_key = rot["key"]  # Update OPUS_API_KEY in the secret manager before revocation

{
  "id": "key_9f3a1c2b",
  "key": "opus_live_xxxxxxxxxxxxxxxxx", 
  "name": "backend-service-prod",
  "scopes": ["opus.read", "opus.write"],
  "created_at": "2026-07-17T12:34:56Z",
  "expires_at": "2026-10-01T00:00:00Z",
  "status": "active"
}