API Usage Patterns

Practical consumption patterns for user apps, MCP integrations, and backend automation teams.

Pattern

Web and Mobile Apps

Authenticate users, call API endpoints with bearer tokens, and handle response codes directly in the app client.

Pattern

MCP Integrations

Use OAuth device flow for local MCP login, then call APIs with short-lived access tokens.

Pattern

Backend Automation

Use workload identity for server-to-server calls and keep credentials out of long-lived storage.

MCP Broker Consumption Flow

Call `BeginMcpOauthDeviceAuthorization` to start login.
Prompt the user to approve the authorization in browser.
Poll `ExchangeMcpOauthDeviceAuthorization` until success.
Use the returned token to call the required API operation.
Handle terminal states (`access_denied`, `expired_token`) without retry loops.

sequenceDiagram
  participant App as Client App
  participant MCP as MCP Server
  participant Aegis as Aegis API
  participant User as End User

  App->>MCP: Request credentialed action
  MCP->>Aegis: BeginMcpOauthDeviceAuthorization
  Aegis-->>MCP: device_code + verification_uri
  User->>Aegis: Approve authorization
  MCP->>Aegis: ExchangeMcpOauthDeviceAuthorization
  Aegis-->>MCP: short-lived access token
  MCP->>Aegis: Call required API operation
  Aegis-->>MCP: Operation result

Implementation Checklist

Use Authorization bearer tokens for all protected API calls.
Validate request payloads against endpoint schemas before sending.
Classify retryable vs non-retryable errors in your client.
Keep short-lived tokens in memory and clear on logout/process exit.
Run integration and E2E tests on all critical request paths.

Where to Go Next

Docs Artifact

Full version is tracked in docs/api/usage-patterns.md.

Open API Explorer

Security Model

Detailed controls and incident-response guidance for broker and workload authentication paths.

Open Security Model