API Access & Tokens

Access surfaces

AIPM exposes its functionality over three surfaces. Choose the one that matches who—or what—is doing the work:

• Web UI — the browser interface operators use day to day. Sign-in is interactive.
• REST API — HTTP endpoints for scripts, integrations, and CI pipelines.
• MCP tool surface — the tool interface that automated agents call.

Both programmatic surfaces—the REST API and MCP—are authenticated with bearer tokens. The web UI uses interactive sign-in instead.

Bearer tokens

A bearer token is a long-lived credential that a caller presents on every request in an HTTP header:

• Send it as Authorization: Bearer <token> on each REST or MCP call.
• Tokens are revocable. An operator can revoke a token at any time, and it stops working immediately—there is no grace period.
• Treat tokens like passwords. Anyone holding a valid token can act with whatever authority that token carries.

Scoping a token

A token does not have to carry full access. It can be scope-limited so an automated agent receives only the narrow authority it needs—for example, restricted to certain operations or to specific projects—rather than the keys to everything.

• Scope each token to the smallest set of operations and projects the caller actually requires.
• Using a token outside its scope is refused. A read-only token cannot perform writes; a project-scoped token cannot reach other projects.

Separation of duties still applies

Authenticating with a token does not let a caller step around AIPM's maker / checker / approver controls:

• The MCP surface binds the acting identity to the authenticated token. A caller cannot supply an arbitrary actor to impersonate someone else and sidestep separation of duties.
• Approvals made over the API are still subject to the three-role rule and the checker-passed gate—exactly as they are in the web UI.

Read-only mode, TLS, and the audit trail

• Read-only mode. When the service runs in global read-only mode, write calls over both REST and MCP are refused regardless of the token presented—useful during maintenance windows. See Running the Service.
• TLS. Programmatic access should always run over TLS. AIPM refuses to bind to a non-loopback address without TLS configured. See Running the Service.
• Auditing. Token-authenticated actions are attributed to the bound identity and recorded in the audit trail like any other action—nothing done over the API is invisible. See Export & Audit.

Good practice

• Least privilege. Scope every token to the minimum operations and projects its caller needs.
• Rotate and revoke promptly. Replace tokens on a schedule, and revoke immediately when one is no longer needed or may be exposed.
• Never expose a token. Do not embed it in client-side code and never commit it to git—keep it in a secret store or environment variable.