Bootstrap Flow

Self-provisioning flow that lets AI agents obtain their own API key through human consent approval.

Key Concepts

The bootstrap flow solves a chicken-and-egg problem: an AI agent needs an API key to request approvals, but creating an API key typically requires dashboard access. Bootstrap lets the agent request its own API key by sending a consent request to the human account owner.

Bootstrap is a public endpoint -- no authentication is required to start it. However, the human must already have a SignedApproval account (created via Google OAuth). The bootstrap flow does not auto-provision new accounts.

Bootstrap Flow Steps

Agent starts bootstrap

The agent (or MCP server) sends a POST to the bootstrap endpoint with the account owner's email:

curl -X POST https://signedapproval.net/api/v1/bootstrap \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@example.com",
    "client_name": "Claude Code MCP"
  }'

Response:

{
  "bootstrap_id": "boot_abc123",
  "status": "pending",
  "message": "Consent request sent. Approve on your device."
}

Human receives consent request

A special bootstrap consent request appears in the dashboard and as a push notification (if enabled). The request clearly identifies the client requesting access.

Human approves or rejects

The human reviews the bootstrap request and decides whether to grant the agent an API key. They authenticate with their registered method (passkey, TOTP, or biometric) just like a regular approval.

Agent polls for the API key

The agent polls the status endpoint until the bootstrap is approved:

curl https://signedapproval.net/api/v1/bootstrap/boot_abc123/status

On approval, the response includes the new API key:

{
  "status": "approved",
  "api_key": "sa_live_newly_provisioned_key..."
}

Important

The API key is returned only once in this response. The agent must cache it immediately (e.g., to ~/.signedapproval/config.json).

Bootstrap Statuses

pending -- Waiting for the human to approve the consent request.
approved -- Human approved; API key is in the response.
rejected -- Human rejected the bootstrap request.
expired -- The bootstrap request timed out (typically 10 minutes).

Security Considerations

Bootstrap requires an existing account -- it will not auto-create users. This prevents unauthorized account creation.
Rate limited to 5 requests per hour per email to prevent abuse.
Bootstrap requests are stored in signedapproval_bootstrap_requests with a short TTL.
The generated API key has full approval:create and approval:read scopes.

MCP Server Bootstrap

The SignedApproval MCP server automates this entire flow. On first launch, if no cached API key exists, it:

Reads the SIGNEDAPPROVAL_EMAIL environment variable.
Calls POST /api/v1/bootstrap.
Polls GET /api/v1/bootstrap/:id/status every 3 seconds.
Caches the API key to ~/.signedapproval/config.json.

To re-bootstrap, delete the cache file:

rm ~/.signedapproval/config.json

Tip

Bootstrap is ideal for developer tools and AI agents that need to be configured once and then run independently. The human approves a single consent request, and the agent has its own API key from that point forward.

MCP Server API Authentication API Keys