Build On The API

Build integrations against the hosted API without breaking the open source boundary.

Contract

A production integration should define:

• Which organization it acts in.
• Which service account and scoped API key it uses.
• Which endpoints it calls.
• What it writes.
• How it reports errors.
• How users can revoke access.

Credentials

Create a service account per integration or agent role. Grant only the scopes it needs, then mint an API key for deployment.

platform-todos service-accounts create codex-runner --scopes tasks:read,tasks:create,runs:read,runs:create

platform-todos service-accounts key <service-account-id> --name production-codex

Keys are shown once. Store them in your secret manager, rotate them when deployment ownership changes, and revoke keys that are no longer used.

Keep the boundary clean

The open source todos package remains the local runtime. todos.md is the hosted control plane.

Validate before release

platform-todos docs catalog --surface api

platform-todos api get /api/v1/capabilities

Documentation expectations

Good docs show the command, required auth, expected output, limits, and failure modes. Keep the words plain.