Agent integration guide

This page is written for an agent operating a terminal with network access. Follow the steps in order; each has a verification command. Everything is scriptable through the CLI (--json) or the OpenAPI document.

Plan

1. Get credentials. If the user has an account, ask for a personal access token (opat_…) and the environment id; otherwise run orishare signup … --save. Verify with orishare --json whoami.
2. Pick the sandbox. Never integrate against production first. orishare --json environments --project proj_… lists both; keep the sandbox id in ORISHARE_ENVIRONMENT.
3. Mint a server key. orishare --json keys create --environment $ORISHARE_ENVIRONMENT --name app. Store the osk_test_… token in the application's secret store. Browser or mobile code gets a publishable key instead (--kind publishable), which can only send events you explicitly allow.
4. Model the events. List the business moments that should earn or unlock something (order.paid, lesson.completed, referral.converted). Send one of each with orishare events send … --sync, then run orishare --json schema show: Orishare records the observed property schema per event name.
5. Write the rules. One JSON document per behavior (see Rules). Use limits for "once per X" semantics rather than conditions on history. Create with rules create --file, check with rules simulate, then --publish.
6. Programs. Add a tier program, rewards or challenges only when the rules need them (orishare api post /tier_programs …). Reference rewards by id in reward.issue actions.
7. Wire the application. Server side: POST /v1/events with the secret key after each business moment, idempotent by the event id you supply (retries are safe). Read GET /v1/customers/{id}/state to render balances and tiers. Client side: publishable key, anonymous_id before login, and a customer_token from POST /customers/{id}/client_token after login.
8. Webhooks. Register an endpoint (orishare api post /webhook_endpoints), store the secret shown once, verify Orishare-Signature (verifyWebhookSignature in the client library) and send a test with orishare api post /webhook_deliveries --data '{"endpoint_id":"whe_…"}'.
9. Promote. orishare config pull from the sandbox, orishare --env env_prod… config push --file … to preview the diff, then --apply. Rules are published in production only by owners and admins.
10. Verify end to end in production with one real event and customers state.

Rules of thumb

• Every creating POST needs an Idempotency-Key; the CLI and client library add one.
• Every response error has type, code, message, param, request_id; the codes are listed at /errors and never change meaning. Retry 429 after Retry-After, never retry 409 stale_write blindly: re-read the resource and send the new If-Match.
• Sync evaluation may fall back to async under load (202 with fallback: true); poll GET /events/{id} until status is evaluated.
• Sandbox data is free and metered for quotas only; production customers are billed.
• POST /ai/rule_drafts (CLI ai draft) returns validated rule documents with assumptions, or 422 ai_draft_rejected with the questions to answer; it never publishes. Create the rule with ai_generation_id set so the draft stays linked to the version it becomes.
• GET /customers/{id}/export (CLI customers export) answers access and portability requests in one document; DELETE /customers/{id} redacts and keeps only the ledger history.