# MachinaLedger — 5-minute self-service quickstart

## Goal
Create a secure workspace, register one agent, issue a scoped credential, and prove the first sandbox event without contacting support.

## 1. Create organization
Generate 32 random bytes and encode them as unpadded base64url. Send them as ownerSecret to POST /v1/onboarding/organizations with an Idempotency-Key.

The response returns tokenPrefix. Your organization admin bearer token is:
tokenPrefix + "." + ownerSecret

The raw owner secret is not persisted by MachinaLedger.

## 2. Register an agent
Use the organization admin token:
POST /v1/agents
{"id":"my_agent","name":"My Agent"}

## 3. Issue an agent credential
Generate another independent 32-byte unpadded base64url clientSecret, keep it locally until the request succeeds, then POST /v1/credentials with an Idempotency-Key:
{"agentId":"my_agent","clientSecret":"<43-char base64url>","scopes":["events:write","ledger:read","registry:read"]}

The final agent bearer token is credential.prefix + "." + clientSecret. MachinaLedger persists only the token hash. Reusing the same Idempotency-Key + clientSecret safely reconstructs the same token even if the first response was lost. Store the token immediately in a secret manager.

## 4. Check onboarding
GET /v1/onboarding/status

The response gives completionPercent, nextStep, safe diagnostics and recommendedNext.

## 5. Prove the connection
POST /v1/onboarding/test-event with an Idempotency-Key:
{"agentId":"my_agent"}

This sends a non-monetary sandbox event through the real Universal Event Core. It cannot move money, issue invoices or post production accounting.

## 6. Connect the real integration
When readyForIntegration=true, choose REST, TypeScript, Python, generic webhook, MCP, x402 or MPP.

Normal onboarding and diagnostics require no human support.

## Diagnose
GET /v1/support/diagnostics with the organization admin key.

The response is safe for an AI support agent: it contains issue codes, severity and exact next actions, but never raw secrets. Normal onboarding failures should be resolved from these diagnostics without human support.