OneLifeVibe Platform

Developer Documentation

API v1 · last updated 25 October 2026 · OpenAPI 3.1

Overview

The Platform API is one credential for 9 independent websites. It is a curated, versioned surface, not a proxy: you can call the 34 listed tools and read the event log, and nothing else on those sites is reachable with a platform key. Every event the platform observes is both retrievable (GET /events) and pushable (webhooks), so polling and push return the same records.

Two directions:

• Inbound — you call the API with an olvp_… key.
• Outbound — the platform POSTs signed events to your HTTPS endpoint. Each world can also publish its own events through ingest, which fans out to every subscriber.

Quick start

1. Apply for a client. The operator approves it.
2. In the console, create a key with the scopes you need and copy it (shown once).
3. Call the API.

export OLV_KEY="olvp_abc123_your32characterSecret"

# What can this key see?
curl -s https://onelifevibe.com/api/platform/v1/worlds -H "Authorization: Bearer $OLV_KEY"

# Which tools exist, with their JSON Schema?
curl -s https://onelifevibe.com/api/platform/v1/tools -H "Authorization: Bearer $OLV_KEY"

# Run one
curl -s https://onelifevibe.com/api/platform/v1/tools/soclasica_search_products \
  -H "Authorization: Bearer $OLV_KEY" -H "Content-Type: application/json" \
  -d '{"arguments":{"query":"serum","limit":5}}'

# Read events, then poll from a cursor
curl -s "https://onelifevibe.com/api/platform/v1/events?limit=25" -H "Authorization: Bearer $OLV_KEY"

Authentication

Send the key as Authorization: Bearer olvp_… or as X-API-Key: olvp_…. Keys are random 32-character secrets; the platform stores only a SHA-256 hash, so a key cannot be recovered — rotate by creating a new one and revoking the old. A key carries a public prefix (olvp_abc123_) that appears in the console so you can tell keys apart without storing the secret.

Key state is checked on every call, in this order: shape → existence → hash → expiry → revocation → client status. A client that is not approved gets 403 client_pending / client_suspended even if the key itself is valid.

Platform keys act as the client. To act as a person, pass subject on a tool call, and only for a person who approved your client — otherwise the answer is 403 consent_required. Console sessions are a separate thing entirely (an HttpOnly cookie plus a CSRF header) and cannot be used against the API.

Scopes and worlds

A scope decides what a key may do; its world list decides where. Both must allow the call.

Worlds: ["*"] or a list such as ["wuuuh","soclasica"]. A key limited to WUUUH gets 403 world_not_allowed on a Soclasica tool even when it holds tools:invoke.

Catalogue

curl -s https://onelifevibe.com/api/platform/v1/

Invoke a tool

{"ok":true,"world":"soclasica","tool":"soclasica_search_products","result":{…},"ms":412}

Events

{"events":[{"id":"evt_…","type":"tool.invoked","world":"soclasica","subject":null,
  "origin":"platform","created_at":"2026-10-25T09:14:03.512Z","data":{"tool":"…","status":200,"ms":412}}],
 "cursor":1843,"has_more":false}

Subscriptions

{"url":"https://api.example.com/onelifevibe","topics":["tool.invoked","world.*"],"worlds":["*"]}

Ingest (worlds)

{"topic":"order.placed","subject":"member:3f1c…","data":{"order":"SC-1042","total":8400}}

Webhooks

Each delivery is a POST with these headers:

Verify against the raw body, before parsing and in constant time:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, headers, secret) {
  const t = Number(headers['webhook-timestamp']);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) throw new Error('stale webhook');
  const expected = 'v1=' + createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(String(headers['webhook-signature'] || ''));
  if (a.length !== b.length || !timingSafeEqual(a, b)) throw new Error('bad signature');
  return JSON.parse(rawBody); // then dedupe on event.id
}

Python equivalent:

import hmac, hashlib, time, json

def verify(raw_body: bytes, headers, secret: str) -> dict:
    t = int(headers["webhook-timestamp"])
    if abs(time.time() - t) > 300:
        raise ValueError("stale webhook")
    expected = "v1=" + hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, headers["webhook-signature"]):
        raise ValueError("bad signature")
    return json.loads(raw_body)

Respond 2xx quickly (flush the body first); anything else is a failure. Body:

{"id":"evt_…","type":"world.event","world":"soclasica","subject":"member:3f1c…",
 "origin":"ingest","created_at":"2026-10-25T09:14:03.512Z",
 "data":{"topic":"order.placed","order":"SC-1042"},
 "delivery":{"endpoint_id":"whe_…","attempts":1}}

Retries

Deliveries are retried after 30s, 2m, 10m, 1h, 6h — 6 attempts in total — then marked dead and visible in the console and in GET /subscriptions/:id/deliveries. A 404 or 410 disables the endpoint after three consecutive failures. Redirects are never followed (a signature must not travel to a new host), requests time out after 10 s, and only the first 512 bytes of your response are kept for diagnosis.

Tool registry

These are the tools a platform key can invoke. Read tools change nothing; write tools change only that person’s own data. Inputs marked ? are optional.

Errors

Every error is JSON: {"error":{"code":"…","message":"…","hint":"…"}}. Codes are stable; match on code, never on the message.

Limits and plans

A call gets 429 rate_limited with X-RateLimit-Limit and X-RateLimit-Remaining when the per-minute allowance is used, and 429 quota_exceeded with Retry-After when the daily allowance is. Bodies are limited to 64 KB; events to 32 KB.

Console and approvals

Clients are approved by an operator. Until then a client can sign in, inspect limits and prepare, but its keys do not work and it receives no events. The console is at /platform/: keys, webhook endpoints with a test button, the last 30 days of usage, delivery history and Stripe billing.

Operator actions use PLATFORM_OPERATOR_TOKEN (or the older GLOBAL_ADMIN_TOKEN) against /api/platform/v1/admin/clients:

curl -s -X POST https://onelifevibe.com/api/platform/v1/admin/clients/<id>/approve \
  -H "Authorization: Bearer $PLATFORM_OPERATOR_TOKEN" -H "Content-Type: application/json" \
  -d '{"plan":"community"}'
# …/reject, …/suspend, …/reinstate are identical in shape.

OpenAPI

The machine-readable description is generated from the same registries as this page: /api/platform/v1/openapi.json. Import it into Postman, Insomnia or your SDK generator.

Questions: support@onelifevibe.com.