Partners & OAuth Apps

This page is for a consumer application — a product that provisions Atribu profiles for its own merchants and reads their attribution, rather than a business measuring its own ads. Vitrina is the reference consumer.

If you are an agency, a developer or an AI agent working on your own account, you want Credentials and the API quickstart instead.

The credential

POST /oauth/token
POST /oauth/revoke

An OAuth app authenticates with client_secret_basic or client_secret_post and receives an atb_live_… API key carrying a tracked oauth_app_id. POST /oauth/revoke is RFC 7009 token revocation.

This is a different OAuth surface from the one an AI agent uses. The agent bootstrap is /oauth/mcp/* — dynamic client registration, PKCE, a human consent screen, an atb_user_… token. See the API quickstart.

Provisioning a merchant

POST /api/v1/profiles

The app-credential branch provisions end to end: it creates the workspace if needed, the profile, the tracking key, and returns the credential the consumer stores for that merchant. It is idempotent on a natural key, so a retried provisioning is not a second profile.

Returning the merchant to your app

A consumer's connect flow bounces the merchant through Atribu and back. The return_url must be listed in the app's allowed_return_origins; an unregistered origin is refused rather than redirected to. When one consent exposes several accounts, the merchant lands on the pending-selection picker — see Connections.

Registering the app

POST   /api/v1/admin/oauth-apps
PATCH  /api/v1/admin/oauth-apps/{id}
DELETE /api/v1/admin/oauth-apps/{id}
POST   /api/v1/admin/oauth-apps/{id}/rotate-client-secret
POST   /api/v1/admin/oauth-apps/{id}/rotate-jwt-secret

Registration is admin-gated — it is Atribu operations work, not self-serve. The two rotations are separate on purpose: client_secret authenticates the app at the token endpoint, jwt-secret signs the id_token_hint that carries the merchant's identity into a consent detour. Rotating one must not invalidate the other.

The Shopify equivalents (/admin/shopify-apps) register a merchant's custom-distribution app and its OAuth scopes; DELETE is a kill-switch.

POST /api/v1/partner/wa-joins

Joins an inbound WhatsApp message to the web session that produced it — the read side of the web→WhatsApp attribution path. Its external_id hashes facts about the message (merchant phone, sender phone, timestamp, normalized text), all of which a retry resends verbatim, so a redelivery is the same conversation rather than a second one.

Generated from openapi.json. The full request and response schema for every operation is in the OpenAPI document.

Next steps