> ## Documentation Index > Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt > Use this file to discover all available pages before exploring further. # Agree to a version > Records that this person agrees to **these words**. The path names a version rather than a document, and that is the whole module: a request naming a document would be agreeing to whatever the text says at the moment the row is written. It refuses anything that is not the version in force — a draft, next month's version, a withdrawn document — with `404`. An acceptance of one of those is a row that reads as proof and is not, which is worse than no row at all. A page rendered before a new version was published gets that `404`; re-read `GET /v1/contact/legal` and offer the current one. Agreeing twice is agreeing once. Both calls answer `200`, and `recorded` says which one actually wrote the row — the timestamp, the address and the user agent are the **first** agreement's, because re-stamping them would move the evidence to whichever retry arrived last. The row keeps the address the click came from and the browser it was made in. It survives an erasure of the person, minus those two fields. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/contact/legal/{versionID}/accept openapi: 3.1.0 info: title: UserKit API version: 1.0.0 description: >- The HTTP surface of UserKit. Two planes share one API. The **staff plane** is what a human uses in the panel: users, organizations, roles, members, keys. The **customer plane** is what a developer's own product uses: contacts, identities, the federated boot and the two proofs of an address. Every error answers the same envelope — `{"error": {"code", "message"}}`. The `code` is a stable contract to branch on; the `message` is for a person and may change. servers: - url: '{baseUrl}' description: The API host. variables: baseUrl: default: https://api.userkit.dev description: Base URL of the API, no trailing slash. security: - sessionToken: [] tags: - name: Gamification description: >- Points, levels and badges: the acts your product wants repeated, written down as rules, and what each of your own users has accumulated by doing them. A rule pays when the fact it names lands — there is no endpoint your users can call that moves a balance, and there is not going to be one. - name: Authentication description: >- Public sign-up, sign-in, two-factor and password recovery for staff accounts. - name: Session description: >- The active session: who the caller is, which organization they are in, and signing out. - name: Account description: The caller's own account — profile, password, sessions, avatar. - name: Two-factor description: >- TOTP setup, activation and recovery codes. Returns 501 when two-factor is unavailable on the server. - name: Organizations description: The organizations a user belongs to, and the active one. - name: Environments description: >- The live and test environments seeded with every organization, and their identity settings. - name: Members description: Memberships and invitations. - name: Roles description: Roles and the permission catalogue they draw from. - name: Audit log description: >- What staff did inside an organization. Append-only, and read behind its own permission. - name: API keys description: Secret keys (`uk_sk_…`) and publishable keys (`uk_pk_…`). - name: Contacts (staff session) description: >- The staff view of the customer plane, opened by a staff session. Reads take `?environment=` as an explicit view parameter. - name: Contacts (API key) description: >- The machine surface, authenticated by an API key. The environment is the key's environment and cannot be named by the caller. - name: Customer plane description: >- Called from the developer's own pages with a publishable key: boot, the two proofs of an address (magic link, email code), and the contact's own session. - name: Customer teams description: >- A customer is a team. Its roster, its invitations and the roles held inside it, administered by the contact's own session. `owner` and `member` always exist; the rest of the vocabulary is the organization's own — see Customer roles. The active customer travels in `X-Customer-Id`. - name: Customer roles description: >- The vocabulary of roles inside your customers, defined per environment. A customer used to be two shapes — the person who administers it and everybody else — which is what `owner` and `member` are, and they are still seeded into every environment and cannot be deleted. Beyond them you define your own: a school has a director, a secretary, a teacher and a student, and none of that fits a boolean. A role carries permissions from **two vocabularies in one list**. Permissions beginning with `$` are UserKit's own and are the only ones we evaluate — `$team.manage` administers the roster, `$billing.manage` the money, `$keys.manage` the team's API keys. Everything else is yours: we store it, we hand it back on the contact's session and in the `customer_permissions` claim of their JWT, and we never read it. That is the point — your backend gates `grades:write` offline, and adding a role never means editing your gate. Reading is `customers:read`, writing `customers:write`. - name: Webhooks description: >- Outbound webhooks: endpoints, the published event catalogue, the delivery log, replay and test sends. Never gated by a plan — webhooks are a developer primitive. - name: Catalogue description: >- The plans, prices and features **you** sell to your own customers. Per environment, a price per currency, and `recurring` or `one_time`. Distinct from the plan you are on with UserKit, which is `GET /v1/organization/entitlements`. - name: Subscriptions description: >- What one of **your** customers is paying you, mirrored from the gateway that charges them. The gateway is the truth about money — it holds the schedule, runs the retries and decides what a proration is worth — so these routes ask it to change something and answer with what it then said. `provider_synced_at` is how stale the copy admits to being. - name: Provider webhooks description: >- Where a payment provider delivers to. Not a surface you call — it is a URL you paste into the provider's dashboard, which is why it sits outside `/v1`: a version bump must never mean editing a setting in somebody else's product. Signed with the secret of the connection named in the path, and safe to retry. - name: Entitlements description: >- What one of **your** customers may do, resolved: the plan their subscription carries, plus the overrides you promised them on top. This is the read your own gate calls, so it is cached and answers in one round trip. It is a different question from `GET /v1/organization/entitlements`, which is the plan **you** are on with UserKit — two catalogues, same word, different money. - name: Credits description: >- How much of a `credit` feature one of **your** customers still holds. The balance is an append-only ledger folded on demand — grants arrive from paid invoices, usage spends against it (`POST /v1/usage`, fail closed), unused credits expire oldest-first, and a support correction is a new signed line rather than an edit. Whether a balance may go below zero, and how far, is the plan's `overdraft_limit`. - name: Customer API keys description: >- Keys **your customers** issue (`uk_ck_live_…` / `uk_ck_test_…`) so your own metered surface can be called per key. An owner of a customer team mints them from their session; your backend treats the string as data and resolves it with `POST /v1/customer-keys/verify` (or passes it as `customer_key` to `POST /v1/usage`). A customer key never authenticates against this API. - name: Customer webhooks description: >- Webhook endpoints **your customers** register from the portal, hearing the events *you* tracked about their team — `POST /v1/track` lines carrying their `customer_id`, delivered under your own event names. Administered under `$webhooks.manage` (the seeded `owner` role holds it), signed and retried exactly like your own endpoints, and gated by your plan: registering answers `webhooks_not_available` on a plan without the capability, and a downgrade stops deliveries without deleting anything. - name: Pricing description: >- The public read of what you sell: live plans and prices, addressed by publishable key, cacheable like JWKS. What a `` renders, and the offer the customer's own checkout sells from. - name: Customer billing description: >- The customer's **own** view of what their team pays, from their session: the subscription, the invoices, and the self-serve acts — checkout, plan change, cancel, resume, the gateway's portal. Reads are for every member; the money acts are owner-only, because spending the team's money is administering the team. - name: Support description: >- The support inbox. A conversation is opened by **your customer** — from the chat widget, or by an inbound email — and staff receive it: there is deliberately no staff-side create. Conversations live in an environment (their subject is a contact); tags and saved replies are the organization's own vocabulary and take no environment. `support:read` and `support:write` gate the staff surface, and every seeded role holds both — the support agent is the archetypal member seat. - name: Help center description: >- The articles you publish so a conversation does not have to happen. Organization-scoped — the product does not differ between live and test the way its contacts do — and versioned append-only: saving creates the next version, publishing points the public page at one of them, and restoring is publishing an old one. The editor rides the support permissions; the published side is public, addressed by your publishable key, and cacheable. - name: Segments description: >- Audiences, defined declaratively over contact attributes, plan, events and activity. One definition compiles into two evaluators that must agree — a query over the environment and an in-process match for one contact — so the count on a screen and the decision made about one person come from the same sentence. Reading is `customers:read` (a segment is a filtered list of contacts); writing is `segments:manage`, because one definition decides who is mailed, surveyed and shown an unreleased feature at once. - name: Feature flags description: >- Release switches the tenant's own product reads. A flag is aimed at a **segment** and never at a filter of its own, so the audience a rollout uses is the audience a survey and a changelog post can use. Two reads serve it: `POST /v1/boot` decides every flag for the person in the round trip the session already cost, and `GET /v1/flags/{publishable_key}` is a public, cacheable document that carries only the switch — polled on a fifteen-second clock and applied over whatever the page booted with. Staff CRUD is `flags:manage`. - name: Onboarding description: >- Checklists the widget renders for your own users, and the funnel behind them. A step is satisfied by a **fact having happened** or by an **entitlement being held** — there is no endpoint that marks one done, by construction, because a checklist whose completion is a button is a measure of who pressed the button. Event steps are written by a bus consumer and are what the funnel counts; entitlement steps are decided on the read against the team the request names, and nothing is stored for them. Staff CRUD and the funnel are `engagement:manage`, the permission the changelog and surveys share. - name: Surveys description: >- NPS and one-question surveys, asked in-app. A survey is aimed at a **segment** or at everybody, fires on a trigger (a fact you named, entering that audience, or N days after somebody signed up) and is held back by a **per-contact cooldown** — the window is per person rather than per survey, which is what makes "nobody is surveyed twice a week" true across every survey you run. Delivery is in-app: `GET /v1/contact/surveys/pending` is what the widget reads and `POST /v1/contact/surveys/{id}/response` is the answer, which announces `survey.response_recorded` to your webhooks. Staff CRUD and the results are `engagement:manage`, the permission onboarding and the changelog share. - name: Changelog description: >- What you shipped, said once. A post is written as a draft, aimed at a **segment** or at everybody, and published by an act of its own — publishing is what puts it in a cacheable public document and announces `changelog_post.published` to your webhooks, so it is a call you make on purpose rather than a field on an edit. Two reads serve it: `GET /v1/changelog/{publishable_key}` is the public release page and carries the posts aimed at nobody in particular; `GET /v1/contact/changelog` is the same list for one signed-in person, with the targeting honoured and their read state on it. Staff CRUD is `engagement:manage`, the permission onboarding and surveys share. - name: Banners description: >- Messages you put on your own users' screens — a strip at the top of the dashboard, a notice in the billing settings, a picture you designed. A banner names a **slot**, which is a place your own developer left room for with ``; nothing is injected into your layout, because the only place a third party may draw is one the page owner declared. It is aimed at a **segment** or at everybody, bounded by an optional window, and only **one banner per slot** is ever returned — highest priority wins, decided in the database so every client gets the same answer. Two kinds: `text` (title, body, icon, tone, button), drawn by the widget in your palette, and `image`, a picture you made and optionally a link. `GET /v1/contact/banners` is what the widget reads and `POST /v1/contact/banners/{id}/dismiss` is the close button. Staff CRUD is `engagement:manage`, the permission onboarding, the changelog and surveys share. - name: Legal description: >- The terms your own customers agree to — terms of service, a privacy policy, a code of conduct — and the record of who agreed to which words. A **document** is a name, an address (`slug`) and a rule about whether agreeing is required; a **version** is the text, and it is frozen the moment it is published, because an acceptance that pointed at an editable body would prove nothing. Publishing may be dated ahead, which is what a thirty-day notice is: the version before it stays in force until then. A new version asks everybody again only when it says `requires_reacceptance` — a corrected typo does not, a new arbitration clause does. `GET /v1/legal/{publishable_key}` is public and cacheable, because a sign-up form has to render the link before there is any session. `required` refuses nothing — there is no sign-up door of UserKit's for it to refuse at — and is reported as `blocking` wherever outstanding agreements are read; what an outstanding agreement does is your product's decision. It never refuses an ordinary API call, and `POST /v1/contact/token` in particular — publishing new terms must mean "everybody is asked", never "everybody is logged out". Staff CRUD is `legal:manage`. - name: Feedback description: >- A feedback board and a public roadmap. Your users ask for things, vote on each other's requests and read what you answered; you triage, merge the duplicates and move a post to `planned`, `shipped` or `declined`. The part a separate feedback tool cannot do is the ranking: `GET /v1/organization/feedback?currency=BRL` weights every post by the **revenue of the distinct customers behind its voters**, so a team of five is worth its revenue once rather than five votes. That number exists on the staff read and nowhere else — the public board says how many people asked, never who pays. Reading is `feedback:read` (owner, admin **and** member, because triage is support work); answering is `feedback:write`. - name: Notifications description: >- Consent for the mail this platform sends your own users, and the unsubscribe link that changes it. Three categories — `marketing`, `product_news` and `surveys` — and every one of them is something a person can switch off. **Transactional mail is not one of them, and there is no value that names it.** A receipt, a dunning notice, a verification link and a password reset keep arriving after somebody unsubscribes from everything, because the absence of the category is what guarantees no screen and no bulk update can produce a person who cannot reset their own password. Consent is honoured at the **send funnel** rather than by whoever composes the message, in the same statement that records the delivery — so a message this person switched off is a message that is never composed, not one that is filtered afterwards. Every non-transactional message carries the unsubscribe link in its footer and the `List-Unsubscribe` / `List-Unsubscribe-Post` header pair on its envelope; no transactional message carries either. - name: Messaging description: >- The message templates outbound campaigns send: a subject, a body, a channel and the **category** the recipient can switch off. The subject and the body are Go `text/template`, compiled **when you save** — a template naming a field the message context does not carry is refused with the field named, never stored to fail per recipient in a job at three in the morning. The context is closed on purpose: `Contact`, `Customer`, `Plan` and `Entitlements`, and nothing else. Whatever a template can reach is reachable by whoever can write one. The category lives on the template rather than on whatever sends it, because a category is a statement about what a message *says*, and the template is the only object here that knows what it says. A campaign inherits it. `messaging:manage` covers the whole surface, reads included — an unsent price change is not something a wider permission should be able to read. - name: Campaigns description: >- The object that reaches out: an audience, a trigger, a sequence and a cap. The audience is always a **segment** — there is no filter of a campaign's own, because an audience defined twice can be previewed one way and mailed another. The words are a **message template**, and the campaign inherits the template's category rather than choosing one. The trigger is one of four: a one-shot to whoever is in the audience now, a fact of a named type, entering the audience, or N days from a timestamp on the contact. Two limits hold at once and they are different promises. `frequency_cap_days` is how long **this** campaign waits before reaching the same person again; a 24-hour cooldown across **every** campaign of the environment sits behind it, so somebody who trips three rules in one hour receives one message. Neither applies to the later steps of a sequence already begun — a cooldown that broke a sequence in half would be a setup that works in test and truncates in production. A contact who has switched the template's category off is recorded as **suppressed with the reason**, which is what lets support answer "why didn't they get it". Writing a campaign is free; **arming** one is what a plan gates. - name: In-app notifications description: >- The message that lands inside your product rather than in an inbox: "your export is ready", "the invoice failed", "someone mentioned you". Your backend posts one over `uk_sk_…` and the person reads it from their own session. It is **transactional by construction** — the request carries no category and there is no field that could carry one, so an in-app notification is not something anybody can unsubscribe from, in the same way a receipt is not. That is not a policy this endpoint applies; it is the only value the write can produce. The write inherits the machine surface's two promises by living on it: an `Idempotency-Key` replays the first response rather than telling somebody the same thing twice, and the per-key rate limit counts the call. The recipient is named by `contact_id` or by your own `external_id` — one of the two, never both, because a request naming two people is a request we would have to guess about. - name: MCP description: >- One endpoint an AI agent's client connects to, so "how many people signed up this week" is answered where the question is asked. Authenticated with an API key, which is also what fixes the environment — no tool takes one as an argument. Every tool is a READ: nothing here creates, changes or deletes anything, and nothing answers with a credential or with the staff audit log. Outside `/v1` because the URL lives in a configuration file rather than in your code. - name: Analytics description: >- The staff read of what happened inside your product: the event explorer, daily counts, saved queries and funnels. Everything here sits behind `analytics:read` — owner and admin by default, because Phase 4's dashboards put revenue on the same screens as event counts. The write path is `POST /v1/events` and the platform's own auth facts; no staff session reaches it. - name: Alerts description: >- Where your organization's bad news gets delivered: Slack, Discord or email. Everything else here is pull — you open a screen and the number is there — and this is the push half, for the five facts nobody opens a screen to discover: the contact meter at 80% and 100%, an environment out of its email allowance, a webhook endpoint turned off after sustained failure, a payment gateway that stopped answering, and a customer's payment being declined. The five are **fixed**. There is no rule to configure and no threshold to set — what fires is decided by the code that publishes each fact, and a second place to re-decide it would be a place that disagrees. What you configure is the destination. The destination is stored encrypted and is never read back: a Slack incoming webhook is a credential, and whoever holds it writes into that channel. Responses carry `destination_hint` — the host for a chat hook, the address for an email. Gated by `alerts:manage`, which only `owner` holds by default. - name: Referrals description: >- Your own users bringing you other users, and what you owe them for it. A code carries its terms (a share in basis points, or a flat bounty), `?ref=CODE` is captured by the SDK as first-touch attribution and recorded at the referred person's first identification, and a paid invoice appends a commission line. First touch is immutable — whoever referred somebody referred them, and a later link cannot take the commission — and a refund appends a negative line rather than erasing the positive one. Payouts are manual: this surface says what is owed and nothing here transfers money. paths: /v1/contact/legal/{versionID}/accept: post: tags: - Legal summary: Agree to a version description: >- Records that this person agrees to **these words**. The path names a version rather than a document, and that is the whole module: a request naming a document would be agreeing to whatever the text says at the moment the row is written. It refuses anything that is not the version in force — a draft, next month's version, a withdrawn document — with `404`. An acceptance of one of those is a row that reads as proof and is not, which is worse than no row at all. A page rendered before a new version was published gets that `404`; re-read `GET /v1/contact/legal` and offer the current one. Agreeing twice is agreeing once. Both calls answer `200`, and `recorded` says which one actually wrote the row — the timestamp, the address and the user agent are the **first** agreement's, because re-stamping them would move the evidence to whichever retry arrived last. The row keeps the address the click came from and the browser it was made in. It survives an erasure of the person, minus those two fields. operationId: acceptLegalVersion parameters: - name: versionID in: path required: true schema: type: string format: uuid description: >- The version in force, from `GET /v1/contact/legal` or the published document. responses: '200': description: >- The agreement, whether this call recorded it or found it already there. content: application/json: schema: type: object properties: acceptance: $ref: '#/components/schemas/LegalAcceptanceReceipt' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/UnverifiedSession' '404': description: >- `not_found` — no version in force with this id. The terms may have changed since the page was loaded. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' security: - contactToken: [] components: schemas: LegalAcceptanceReceipt: type: object description: What an acceptance call answers with. properties: id: type: string format: uuid document_id: type: string format: uuid slug: type: string version_id: type: string format: uuid version: type: integer accepted_at: type: string format: date-time description: The FIRST agreement's moment. A retry does not move it. recorded: type: boolean description: >- Whether this call is what wrote the row. Stated rather than inferred from the status — "you agreed just now" and "you had already agreed" are both success. Error: type: object description: Every error in this API answers this envelope. properties: error: type: object properties: code: type: string description: Stable. Branch on this. message: type: string description: For a person. May change. required: - code - message required: - error example: error: code: forbidden message: your role does not allow this action responses: BadRequest: description: '`invalid_request` — the body or a parameter is malformed.' content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- `unauthorized` — missing, malformed, expired or revoked credential, and nothing else: it says the credential is gone, so a client is right to discard it and sign in again. A well-formed credential from the wrong family says so: "this endpoint expects a staff session token, not an organization API key". A LIVE staff session aimed at an organization it is not a member of is `not_a_member` (403), never this. content: application/json: schema: $ref: '#/components/schemas/Error' UnverifiedSession: description: >- `unverified_session` — this session claims an identity that was never proven, which is what a federated boot with no identity hash produces. Sign in through a flow that proves the person (magic link, email code) or boot with a valid hash. Anonymous sessions are not affected. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- `rate_limited` — too many requests. `Retry-After` carries the window in seconds. The counters are shared across instances. When that store cannot be reached each instance counts on its own instead: the limits get looser, never absent. headers: Retry-After: schema: type: integer description: Seconds until the window resets. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: sessionToken: type: http scheme: bearer description: >- A staff session token, `uk_st_…`. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; `not_a_member` (403) is about the organization named in `X-Organization-Id` and leaves the token good for the others. contactToken: type: http scheme: bearer description: >- A contact session token, `uk_ct_…`. Belongs to one of the developer's own users, and reads only that user's data. ````