Integrations

An integration moves data between TIMES and another service. It usually has a configure surface and a connect block.

{
  "kind": "integration",
  "mode": "runtime",
  "ui": { "framework": "vite", "runtime": "iframe", "surfaces": ["configure"], "entry": "./dist/index.html", "uses_times_tokens": true },
  "scopes": { "required": ["invoices:read", "events:subscribe", "state:read", "state:write"] },
  "connect": { "mode": "oauth", "oauth": { "provider": "telegram" } }
}

Connection lifecycleCopy Anchor Link

1. The merchant installs the integration and opens Configure.
2. Your configure screen calls client.api.connection() to read the status.
3. If disconnected, the host runs the OAuth flow. Tokens are stored by TIMES.
4. Your worker calls POST /api/v1/apps/runtime/v1/provider/token to get a short-lived provider token when it needs one.
5. client.api.disconnectConnection() clears secrets and keeps the integration installed.

EventsCopy Anchor Link

Subscribe with client.api.subscribe('invoice.created', handler) in the iframe, or receive the same events on your worker webhook in runtime mode.