Skip to content

Session protocol v1

The authoritative models and endpoint declarations are argus.contracts.session_protocol; the deterministic release artifact is release/session-protocol.v1.json. These are identity-management endpoints, separate from both financial fact/discovery tools and the 67 personal tools. The identity component also publishes its own OpenAPI document. No account revocation, deletion or identity mutation is exposed as an Agent tool here.

All endpoints use POST and strict JSON objects. Responses are private, no-store. The start request selects an existing configured CLI client key; it cannot register an OAuth application, change a callback, scope, subject or resource. The response contains a five-minute login proof and a standard PKCE authorization URL. Keep the proof in memory; do not record it or send it to the browser. Completion requires that proof, matching state and the real short-lived code. It returns one opaque Argus session credential and safe session metadata.

/session/v1/inspect and /session/v1/refresh require the opaque credential in Authorization and the exact bound resource in JSON. They return safe metadata and a server-established principal, never upstream access or refresh credentials. The principal includes verified client/resource and registered session/receipt metadata so execution can recheck persisted rejection at delivery. These fields are output from the identity component, not caller-selectable identity inputs. Credential possession does not grant a different resource, client or private domain. Ordinary resource servers use a configured trusted service URL and their own fixed API/MCP resource; the requester cannot select an introspection server. TLS is mandatory except dedicated loopback test/development services. Redirects are refused. Errors never echo request credentials or provider response bodies.

Run the component using the existing Uvicorn factory support for argus.auth.session_api:create_session_app, with access logging disabled. ARGUS_SESSION_CONFIG names a private mounted JSON configuration containing environment, issuer, institution_id, dedicated database_url, clients, versioned encryption_keys, active_key and independent handle_key. Keys are base64 32-byte values generated outside the repository. Each pre-registered client has client_id, callback_url, resource, scopes, kind and upstream_audience; optional client_secret stays in this private file. Ordinary API/MCP/worker processes do not mount it. Their nonsecret oauth.session_service_url points to the component.

Production origins, exact client registrations, database roles and secret mounts are checked by the deployment contract. The client does not silently fall back to a client-owned token exchange when a session component is unavailable. Legacy explicit Bearer/API-key compatibility remains subject to its own controls.

Production identity configuration also requires revocation: fixed organization, application names keyed by their registered client IDs, and a separate management client ID/secret. Only the identity component mounts this configuration. Revoking access never deletes the owner's records; deletion is a separate, confirmed owner action.