# Self Bank Agent Integration Guide

## Overview

This guide describes how partners and autonomous agents engage with the Self Bank sandbox-first agent surface. It complements the OpenAPI contract and the Agent API page, focusing on integration flow, control principles, and engagement.

## Intended users

- Engineering teams integrating an agent or automation product with Self Bank.
- Architects evaluating Self Bank as an agent-ready integration target.
- Partner organizations preparing a structured engagement with Self Bank.

## Integration prerequisites

- Ability to read the OpenAPI 3.1 contract and generate or hand-write a typed client.
- Secure storage and rotation for issued bearer tokens.
- Logging and traceability on the agent side, correlated with returned request identifiers.
- Acceptance of sandbox-first boundaries (no attempt to bypass scopes or environment markers).

## Integration model

- Sandbox-first: integration begins and is validated end-to-end against the public sandbox.
- Contract-driven: all interactions conform to `/api/openapi-agent-v1.yaml`.
- Scope-limited bearer auth: agents receive JWTs carrying only the required scopes.
- Human-in-the-loop: any move from sandbox to production-affecting workflows requires human review and explicit enablement.

## Current capability set

- Product and service catalog read (`catalog.read`)
- Onboarding simulation (`simulation.onboarding`)
- Payment simulation (`simulation.payments`)
- Account-opening simulation (`simulation.account_opening`)
- Operational analytics summary (`analytics.summary.read`, planned capability)

## Recommended integration flow

1. Discover: review `/api/agent`, `/agents/skills`, and the OpenAPI contract.
2. Model: map your use case to specific scopes and skills.
3. Implement: build against `https://cube.self.team/api/agent/v1`.
4. Validate: cover success and error paths (`400`, `401`, `403`) for each endpoint.
5. Document: capture audit trails, request identifiers, and observed behavior.
6. Engage: contact Self Bank to discuss controlled expansion beyond sandbox.

## Security and control principles

- Scope minimization: never request scopes beyond the immediate use case.
- Token hygiene: store tokens securely, rotate, and never expose in client code.
- Boundary respect: do not attempt to bypass the `environment: sandbox` marker.
- Auditability: log request identifiers and decisions on the agent side.
- Reversibility: assume sandbox responses are illustrative; never treat them as production state.

## Environment model

- Single public environment: `sandbox`.
- All sandbox responses are marked `environment: sandbox`.
- Non-sandbox environments are not part of the public agent surface and are governed by direct engagement with Self Bank.

## What is not in scope

- Real customer data, real accounts, or real fund movement.
- Production-grade SLAs, rate limit guarantees, or uptime commitments for the sandbox.
- Self-service issuance of production credentials.
- Capabilities not declared in the OpenAPI contract or the agent skills index.

## Readiness criteria

An integration is considered ready for evaluation when:
- All target endpoints are exercised with valid and invalid inputs.
- Error handling covers `400`, `401`, `403`, and unexpected responses.
- The agent respects scope boundaries and the sandbox environment marker.
- Audit logs correlate with `error.requestId` and successful response identifiers.

## Evaluation outcomes

- `sandbox-validated` — fully working against the sandbox contract.
- `evaluation-in-progress` — under review by the Self Bank team.
- `requires-changes` — specific items must be addressed before re-evaluation.
- `not-eligible` — use case is outside the current public agent surface.

Promotion beyond the sandbox is never automatic and is governed by the engagement model below.

## Engagement model

- Discovery: review public documentation and the OpenAPI contract.
- Sandbox build: implement and validate against the sandbox base URL.
- Enterprise discussion: contact Self Bank to align on scope, controls, and timeline.
- Controlled enablement: any non-sandbox capability requires a signed engagement and explicit configuration by Self Bank.

## Related resources

- Agent API: https://cube.self.team/api/agent
- Agent skills: https://cube.self.team/agents/skills
- OpenAPI contract: https://cube.self.team/api/openapi-agent-v1.yaml