TelaroDocs
Build · API

Use the SDK first. Inspect the HTTP contract when needed.

Telaro separates public trust reads from organization-scoped procurement. This page explains the boundary, authentication, and recovery rules for direct API consumers.

Surfaces

Choose the API that owns the data

SurfacePurpose
Public APIAgent profiles, trust, claims, activity, ecosystem, and public discovery reads.
Procurement APIPrivate organization setup, members, policy, budget, requests, approvals, execution, receipts, and audit.
Chain RPCAuthoritative Solana account and transaction state. Use an SDK client for typed instruction construction.
Authentication

Procurement sessions start with wallet proof

  1. Create a short-lived challenge for the exact wallet.
  2. Sign the exact returned message with ed25519.
  3. Exchange the challenge, wallet, and base58 signature for a session.
  4. Trusted servers send the bearer token and x-organization-id with tenant requests.
  5. Rotate the session before expiry and revoke it on sign-out or access change.
HTTP
Authorization: Bearer <organization-session>
x-organization-id: org_acme
idempotency-key: <unique-command-key>

The product browser does not receive this bearer. It calls the same-origin /api/procurement gateway, which uses an HTTP-only, SameSite Strict cookie and requires Origin plus CSRF checks for commands. Membership is resolved from the authenticated wallet. Actor and organization identifiers in a request body cannot override that server context.

Session lifecycle
POST   /api/v1/auth/sessions/current/refresh
DELETE /api/v1/auth/sessions/current
Command rules

Every mutation is replay-safe

  • Send a unique idempotency key for every logical mutation.
  • Retry the same command with the same key and identical body.
  • Use a new key when the desired business action changes.
  • Read domain and financial state after a timeout before issuing another command.
  • Handle stable reason codes instead of matching human-facing error copy.
Procurement v1

Route groups follow the business lifecycle

Route groupOperations
/authWallet challenges plus session creation, rotation, and revocation.
/organizationsList memberships and atomically provision a bounded organization.
/organizationRead setup and manage Owner, Admin, Approver, Requester, Finance, and Auditor members.
/procurement/requestsCreate a request, run policy evaluation, and discover candidates.
/procurement/executionsFreeze terms, decide approval, execute, sync, verify, settle, dispute, or reclaim.
/procurement/receiptsRead organization-scoped settlement records.
/procurement/audit-eventsRead the ordered tenant activity ledger.
Contracts

Keep generated clients tied to live schemas

Public API

OpenAPI

Public read and trust endpoints exposed by the product application.

Open JSON schema →
Procurement API

OpenAPI

Private control plane routes, schemas, auth, and command requirements.

Open JSON schema →