API & Postman

Agentissimo ships a machine-readable contract for both HTTP surfaces, generated from the handlers. Each service’s OpenAPI spec is committed alongside its crate; the Postman bundle lives in a shared dev_tooling/postman/:

Surface	OpenAPI spec	Postman collection
Local daemon (loopback)	service_daemon/contract/openapi.json	agentissimo-daemon.postman_collection.json
Hosted backend	service_backend/contract/openapi.json	agentissimo-backend.postman_collection.json

Both collections share one environment file, dev_tooling/postman/agentissimo.postman_environment.json. Adoption is incremental — endpoints gain their contract as they are next touched, so the specs cover a growing subset of the routes.

Import into Postman

1. Import the two *.postman_collection.json files and the agentissimo.postman_environment.json environment.
2. Select the Agentissimo environment (top-right).

Daemon collection

The daemon binds 127.0.0.1/::1 and its loopback guard returns HTTP 403 to non-loopback callers, so Postman must run on the same host and local operations need no token. Set daemon_port to the port the daemon printed on boot (see Ports & endpoints).

Backend collection

/api/* requests send Authorization: Bearer {{access_token}}. Three credentials fit that slot, in preference order:

1. OAuth service principal (machines: CI, scripts, automation) — preferred.
2. OAuth authorization-code + PKCE (third-party tools acting for a user).
3. API key — supported, least preferred.

Browser sessions use a WorkOS JWT: open the auth (bootstrap) folder, run login in a browser to complete the WorkOS AuthKit flow, set {{access_token}} from the session (refresh renews it), and set {{backend_url}} to the backend base URL.

/ws/runner is a WebSocket the local daemon dials with a backend-issued runner token ({{runner_token}}), documented in the collection rather than as a REST request.

OAuth for machines (preferred): service principals

A service principal is a WorkOS Connect M2M application bound to your organization: a machine identity with a client id and a rotatable secret that mints short-lived access tokens at WorkOS — no static long-lived bearer in your CI config, and Agentissimo stores no credential material at all.

1. In the app, open Settings → Security → Service principals and Create principal (pick read or read_write scope — the agentissimo:read / agentissimo:read-write permission slugs on the application). The client secret is shown once — copy it then.

2. Mint a token at WorkOS, then call the Agentissimo API with it:

   TOKEN=$(curl -s -X POST "https://api.workos.com/oauth2/token" \
     -d grant_type=client_credentials \
     -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" \
     -d scope="agentissimo:read-write" \
     | jq -r .access_token)
   curl -H "Authorization: Bearer $TOKEN" "$BACKEND/api/spaces"

   In Postman, set {{oauth_client_id}} / {{oauth_client_secret}} and run mint token in the oauth (M2M — preferred) folder — its test script fills {{access_token}} for the whole collection.

Rotate the secret from the same panel when it may have leaked; Revoke the principal to delete the application at WorkOS — its credentials stop minting immediately, and outstanding tokens expire within their lifetime.

OAuth for tools (U2M): authorization-code + PKCE

A third-party tool acts on your behalf via the standard browser flow — run entirely at WorkOS Connect. Register the tool under Settings → Security (POST /api/oauth-clients: name + redirect-URI allow-list; this creates a Connect OAuth application), then point it at WorkOS’s discovery document — {{connect_issuer}}/.well-known/openid-configuration names the authorize, token, and JWKS endpoints. In Postman, use the built-in Authorization Code (With PKCE) helper with those URLs.

Authenticate with an API key (least preferred)

API keys remain fully supported for clients without OAuth plumbing. Prefer a service principal for anything new — a key is a static long-lived secret; OAuth tokens expire in an hour.

1. In the app, open Settings → Security → API keys and Create key. The full key is shown once — copy it then; you cannot retrieve it again.

2. Send it on every /api/* request:

   curl -H "Authorization: Bearer $AGENTISSIMO_API_KEY" "$BACKEND/api/spaces"

   In Postman, set {{pat}} and use it as the bearer for the backend collection instead of {{access_token}}.

The key authenticates as your organization (tenant) and carries a read or read_write scope — a read key is rejected by any mutating route (OAuth tokens carry the same scopes). Revoke a key from the same section; revocation takes effect on the next request. Never commit a key to source control.

Migrating a key to a service principal: create a principal with the same scope, swap the static key in your CI for the mint-then-call step above, then revoke the key.

Keys are managed by WorkOS (Agentissimo holds no key material). One consequence: API-key authentication depends on WorkOS being reachable. A WorkOS incident is an API-key-auth incident and blocks new OAuth token minting — but already-issued OAuth tokens and browser sessions keep verifying locally (JWKS).

Keeping it current

The specs and collections are generated, never hand-edited. When an endpoint changes, its annotation and the generated contract/ + dev_tooling/postman/ artifacts change in the same change, and CI fails on drift. Regenerate with:

cargo run -p agentissimo-service-daemon --bin gen-openapi
cargo run -p agentissimo-backend --bin gen-openapi
node scripts/gen-api-artifacts.mjs