@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

package/dist/docs/reference/dashboard/steps.mdx

@@ -0,0 +1,37 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Steps
+
+A step is one screen or card that a visitor sees during an experience. Each step
+holds one or more fields. A field collects data or shows content.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/steps"
+  alt="The steps list for a workspace on the Picked dashboard"
+/>
+
+## Set up a step
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Key**: The identifier that your application uses for this step. Your
+visitors do not see it.
+
+**Layout Name**: The name of the component layout that renders this step. Examples
+are `card`, `modal`, and `fullscreen`.
+
+A step can also carry a **Step Layout**. A step layout is a reusable CMS schema, and
+it gives the step a Content Entry. See [Page and Step Layouts](/reference/dashboard/content/layouts).
+
+## Related
+
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+
+- [How to build a flow](/how-to/build-a-flow) — add a step and assign fields to it.
+- [How to reuse a step, a field, or an action](/how-to/reuse-a-step-field-or-action)
+- [Page and step layouts](/reference/dashboard/content/layouts) — the step layout schema.

package/dist/docs/reference/dashboard/team-management.md

@@ -0,0 +1,29 @@
+---
+type: reference
+layout: docs
+---
+
+# Team management
+
+Control who can reach your organization and what each person can do. An organization
+is the top-level container for your projects and members.
+
+## Organizations
+
+An organization groups your projects, your members, and your settings. You can belong
+to more than one organization.
+
+To move between organizations, use the organization control at the top of the
+sidebar.
+
+## Roles and permissions
+
+Each member holds a role, and the role controls what the member can reach. A role
+decides whether a member can create a project, edit an experience, control other
+members, or read a report.
+
+Give each member the smallest role that the work of that member needs.
+
+## Related
+
+- [How to invite and remove members](/how-to/invite-and-remove-members)

package/dist/docs/reference/dashboard/workspace-versioning.mdx

@@ -0,0 +1,30 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Workspace versioning
+
+When you publish, Picked makes an immutable snapshot of your workspace. A project
+always serves exactly one version, the *live* version. A roll-back moves the live
+pointer of the project to an earlier snapshot. It changes no data.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/publish-history"
+  alt="The Publish history page with published workspace versions and the Live and Restore actions"
+  hide={['[data-testid="version-row-relative-time"]']}
+/>
+
+## Publish history
+
+The **Publish history** page lists each published version of every workspace in the
+project, the newest first. The version that Picked serves now carries a **Live**
+badge.
+
+## Related
+
+- [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
+  changes no data.
+- [How to roll back a published version](/how-to/roll-back-a-published-version)

package/dist/docs/reference/dashboard/workspaces.mdx

@@ -0,0 +1,76 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Workspaces
+
+A workspace is one version of the configuration of your project. Use a workspace to hold
+a change, to see a preview of it, and to publish it when it is ready.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces"
+  alt="The workspaces list inside a project on the Picked dashboard"
+  hide={['[data-testid="workspace-row-relative-time"]']}
+/>
+
+## How workspaces work
+
+Each project has a workspace that holds your experiences, feature flags, steps, fields,
+actions, and conditions. When you make a change in the dashboard, that change stays in
+the workspace until you publish it. A change to a flow, to a feature flag, or to a step
+all behave the same way.
+
+A workspace is in one of three states:
+
+- **Live** — the workspace that the SDK serves to your visitors. Each project has
+  exactly one live workspace.
+- **Draft** — a workspace that no visitor sees. You can edit a draft, see a preview
+  of it, and publish it to make it live.
+- **Archived** — a draft that you put to one side. An archived workspace is still
+  editable, but it does not appear in the default workspaces list.
+
+## Change previews
+
+The publish modal shows a side-by-side change preview. It compares the current
+workspace against the last published snapshot. Use it to see exactly what your
+visitors get after you publish.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences?action=publish"
+  alt="The publish modal with a change preview of added experiences, steps, and conditions"
+  selector='[role="dialog"]'
+  wait='[role="dialog"]'
+  hide={['[data-testid="publish-diff-replaces-version"]']}
+  renderWidth={720}
+  renderHeight={579}
+/>
+
+The preview puts the changes into groups: experiences, feature flags, steps, fields,
+actions, and conditions. Each row shows whether the record was **added**, **removed**,
+or **modified**. For a modified record, expand the row to see which properties changed.
+
+Some changes break other records. An example is a field that you remove while other
+steps still point at it. The change preview shows a banner above the diff for these
+entries, so that you can look at them again before you publish.
+
+The first publish of a workspace has no earlier snapshot to compare against. The
+publish modal shows the contents of the workspace as the first publish, with no diff.
+
+## Unpublished changes
+
+The workspace records whether anything changed since the last publish. The toolbar then
+shows a warning badge. It counts a change to any of these:
+
+- An experience or a feature flag.
+- A step, a field, an action, or a condition.
+
+## Related
+
+- [About workspaces and versions](/explanation/workspaces-and-versions) — why a draft and
+  a version are separate.
+- [How to see a preview of a workspace](/how-to/preview-a-workspace)
+- [How to publish a workspace](/how-to/publish-a-workspace)
+- [How to archive or delete a workspace](/how-to/archive-or-delete-a-workspace)

package/dist/docs/{delivery-api → reference/delivery-api}/experience-content.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -16,7 +17,7 @@ GET /api/v1/projects/:projectId/experiences/:id/content
 | --- | --- | --- |
 | `projectId` | path | The project the experience belongs to. |
 | `id` | path | The experience to fetch content for. |
-| `preview_token` | query | Optional. Returns preview (unpublished) content when present. |
+| `preview_token` | query | Optional. With it, the endpoint returns preview content, which is unpublished. |
 
 ## Response
 
@@ -40,11 +41,14 @@ GET /api/v1/projects/:projectId/experiences/:id/content
 | `versionId` | `string \| null` | The published version id, or `null` on preview. |
 | `content[].id` | `string` | The Content Entry id. |
 | `content[].contentModelKey` | `string \| null` | The layout's Key, or `null` when it cannot be resolved. |
-| `content[].data` | `object` | The entry data, matching the layout schema. |
+| `content[].data` | `object` | The entry data. It matches the layout schema. |
 
-## HTML asset inlining
+## An HTML asset comes back in the response
 
-When the layout has an [HTML asset](/content/asset-library) field, its value arrives inlined. The reference is rewritten to `{ id, content }`, where `content` is the uploaded HTML as a string (or `null` when it cannot be resolved):
+A layout can have an [HTML asset](/reference/dashboard/content/asset-library) field. The value of that
+field arrives inside the response. The endpoint changes the reference to
+`{ id, content }`. There, `content` holds the HTML that you uploaded, as a string. It
+is `null` when the endpoint cannot resolve it:
 
 ```json
 {
@@ -82,4 +86,12 @@ curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
 }
 ```
 
-See [Project Config](/delivery-api/project-config) for the endpoint that links steps to entries, [Asset Library](/content/asset-library) for HTML assets, and [Server Snapshot](/sdk/ssr/serialize) for how the SDK consumes this content.
+See [Project Config](/reference/delivery-api/project-config) for the endpoint that links a step
+to an entry. See [Asset Library](/reference/dashboard/content/asset-library) for an HTML asset. See
+[Server Snapshot](/reference/sdk/ssr/serialize) for how the SDK reads this content.
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis)
+- [Project config](/reference/delivery-api/project-config)
+- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling)

package/dist/docs/reference/delivery-api/index.md

@@ -0,0 +1,45 @@
+---
+type: reference
+layout: docs
+---
+
+# Delivery API
+
+The Delivery API is a public REST API. It is read-only, and it serves the published
+configuration of your project together with your page content. It is separate from the
+GraphQL management API.
+
+## Base URL and versioning
+
+All Delivery API routes are versioned under `/api/v1`:
+
+```
+https://api.picked.app/api/v1
+```
+
+## Published content and preview content
+
+Each endpoint serves two surfaces:
+
+- **Published** content is anonymous. Anybody can read your published configuration and
+  your published content.
+- **Preview** content needs a `preview_token` query parameter. With it you can render
+  an unpublished draft before you make it live.
+
+The management API holds the preview token of a workspace in the `previewToken`
+field. The preview action in the dashboard also makes one for you.
+
+## Endpoints
+
+| Endpoint | Description |
+| --- | --- |
+| [Project Config](/reference/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published configuration of the project, with the content link of each step. |
+| [Experience Content](/reference/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries of an experience. |
+
+Both endpoints share some behaviour. See
+[Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis) — which one to use, and why they are
+  separate.

package/dist/docs/reference/delivery-api/preview-caching-crawling.md

@@ -0,0 +1,79 @@
+---
+type: reference
+layout: docs
+---
+
+# Preview, cache, and crawlers
+
+Both Delivery API endpoints share this behaviour: the preview token, the cache, CORS,
+and what a crawler can read.
+
+## Preview tokens
+
+Pass `?preview_token=<token>` to read unpublished content. Both endpoints take it,
+and both return `versionId: null` for a preview. An invalid token returns `401`.
+
+```bash
+curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
+```
+
+The [management API](/tutorials/first-api-call) holds the preview token of a workspace in the
+`previewToken` field. The preview action in the dashboard also makes one for you.
+
+Use the same token for the project configuration request and for the experience content
+request. Both then come from the same preview.
+
+## Cache
+
+The cache rules depend on the surface and on the client that makes the request. The
+SDK sends a `Picked-Client: sdk` request header:
+
+| Request | `Cache-Control` |
+| --- | --- |
+| Published, `Picked-Client: sdk` | `public, s-maxage=60, stale-while-revalidate=86400` |
+| Published, other clients | `private, no-store` |
+| Preview | `no-store` |
+
+A published response that a cache can hold also sends `Vary: Picked-Client`. A shared
+cache therefore keys on the client header. It never gives a body that it cached for
+the SDK to a request from another client.
+
+## CORS
+
+Both endpoints can be read from another origin. An `OPTIONS` preflight returns `204`
+with the CORS headers:
+
+| Header | Value |
+| --- | --- |
+| `Access-Control-Allow-Origin` | `*` |
+| `Access-Control-Allow-Methods` | `GET, OPTIONS` |
+| `Access-Control-Allow-Headers` | `Content-Type, Picked-Client, Picked-Version, traceparent, tracestate` |
+
+## Crawlers and search rank
+
+A crawler can read both endpoints, so a search engine can read your published
+content. A preview URL is disallowed, so a draft never reaches the index. These are
+the `robots.txt` rules:
+
+```
+User-agent: *
+
+# Let a crawler read the public project configuration and experience content.
+Allow: /api/v1/projects
+Allow: /api/v1/projects/*/experiences/*/content
+
+# Keep a preview response, which is a draft, away from a crawler.
+Disallow: /api/v1/projects/*preview_token=
+
+# Everything else stays disallowed: GraphQL, MCP, internal routes, and the ping.
+Disallow: /
+```
+
+See [Project Config](/reference/delivery-api/project-config) and
+[Experience Content](/reference/delivery-api/experience-content) for the endpoints.
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
+  index.
+- [How to render an unpublished preview](/how-to/render-an-unpublished-preview)

package/dist/docs/{delivery-api → reference/delivery-api}/project-config.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -15,21 +16,23 @@ GET /api/v1/projects/:projectId
 | Parameter | In | Description |
 | --- | --- | --- |
 | `projectId` | path | The project to fetch config for. |
-| `preview_token` | query | Optional. Returns the preview (unpublished) config when present. |
+| `preview_token` | query | Optional. With it, the endpoint returns the preview configuration, which are unpublished. |
 
 ## Response
 
-The response carries the project's experiences and steps. Each step includes `layoutContentId`, the reference to the Content Entry that backs that step's layout. Use it to know which experiences have content to fetch from the [Experience Content](/delivery-api/experience-content) endpoint.
+The response carries the project's experiences and steps. Each step includes `layoutContentId`, the reference to the Content Entry that backs that step's layout. Use it to know which experiences have content to fetch from the [Experience Content](/reference/delivery-api/experience-content) endpoint.
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `id` | `string` | The project id. |
 | `versionId` | `string \| null` | The published version id, or `null` on preview. |
-| `steps[].layoutContentId` | `string \| null` | The Content Entry backing this step, or `null` when the step has no content. |
+| `steps[].layoutContentId` | `string \| null` | The Content Entry of this step, or `null` when the step has no content. |
 
-## Published vs preview
+## Published content and preview content
 
-On the published surface, `versionId` is the published version id. On the preview surface (`?preview_token=...`), `versionId` is `null` because there is no published version. See [Preview, Caching & Crawling](/delivery-api/preview-caching-crawling).
+For published content, `versionId` holds the ID of the published version. For preview
+content, which you read with `?preview_token=...`, `versionId` is `null`, because
+there is no published version. See [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
 
 ## Example
 
@@ -53,4 +56,10 @@ curl https://api.picked.app/api/v1/projects/proj_123
 }
 ```
 
-Pass the config to `serialize()` on your server to produce an SSR snapshot. See [Server Snapshot](/sdk/ssr/serialize).
+Pass the config to `serialize()` on your server to produce an SSR snapshot. See [Server Snapshot](/reference/sdk/ssr/serialize).
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis)
+- [Experience content](/reference/delivery-api/experience-content)
+- [How to server-render a page](/how-to/server-render-a-page)

package/dist/docs/reference/glossary.md

@@ -0,0 +1,173 @@
+---
+type: reference
+layout: docs
+---
+
+# Glossary
+
+Every term that Picked uses, and what each one means. The dashboard, the API, and the SDK
+sometimes use different words for the same thing. This page gives the word that the
+documentation uses, and it names the others.
+
+## Accounts and access
+
+| Term | What it is |
+| --- | --- |
+| **Organization** | The top level. It holds your projects, your members, and your settings. You can belong to more than one. |
+| **Member** | A person in an organization. Each member holds one role. |
+| **Role** | What a member can reach. It decides whether a member can create a project, edit an experience, or read a report. |
+| **API key** | A credential for a server-to-server integration. It belongs to an organization, it can belong to one project, and it carries scopes. |
+| **Scope** | One permission, written `resource/action`, such as `organization/read`. A scope decides which operations a caller can do. |
+| **Session** | The result of a sign-in. It holds an access token, a refresh token, and the time at which the access token expires. |
+| **User** | A person who signs in to the Picked dashboard. A user is not a visitor. |
+| **Invitation** | An offer to join an organization, sent to an email address. It waits until the person accepts it. |
+| **MFA factor** | A second credential on an account, such as a telephone number. |
+
+## Projects and versions
+
+| Term | What it is |
+| --- | --- |
+| **Project** | One site or one application. Each project has its own experiences, content, and configuration. |
+| **Project configuration** | The published settings of a project: its experiences and steps, and the content link on each step. The Delivery API serves it, and the SDK reads it. The SDK parameter is `projectConfig`. |
+| **Workspace** | One version of the configuration of a project. You hold a change in a workspace, see a preview of it, and publish it. |
+| **Draft** | A workspace that no visitor sees. |
+| **Live** | The workspace whose snapshot the SDK serves. Each project has exactly one. |
+| **Archived** | A draft that you put to one side. It is still editable, and it is out of the default list. |
+| **Version** | An immutable snapshot of a workspace, made when you publish. The **Publish history** page lists them. |
+| **Preview** | A view of an unpublished workspace on your own site. It reaches your browser only. |
+| **Preview environment** | A named target that a preview opens against. |
+| **Project settings** | The settings of one project, which you edit in the dashboard. These are not the project configuration that the Delivery API serves. |
+
+## Experiences
+
+| Term | What it is |
+| --- | --- |
+| **Experience** | Personalized content that Picked serves to a visitor. It is a Flow or a Page. |
+| **Flow** | An interactive experience of more than one step, which the browser renders. |
+| **Page** | A standalone experience that your server renders from a content entry, for content that a search engine must read. |
+| **Step** | One screen that a visitor sees. It holds fields. |
+| **Field** | A data input inside a step. It collects a name, an email address, a preference, or a choice. |
+| **Field option** | One choice in a field that has a fixed set of choices. Each option carries a value, and it can carry a condition. |
+| **Action** | A side effect that starts when the flow reaches it. Your application registers a handler for it. |
+| **Condition** | A rule that decides whether a visitor sees something, or which branch a flow takes. |
+| **Predicate** | A function that you register on the client, so a condition can read data that only your application holds. |
+| **Response** | A value that a visitor sends through a field. |
+| **Origin** | The node where every flow starts. |
+| **Node** | One part of a flow on the canvas: an origin, a step, an action, or a condition. |
+| **Handle** | A connection point on a node. An input handle is on the left, an output handle on the right. |
+| **Key** | The stable identifier of a step, a field, an action, or a condition. Your application and your API calls both use it. You set it one time, and you cannot change it. |
+| **Layout name** | The name of the component that renders a step, such as `card` or `modal`. |
+| **Target** | The element that an experience renders against, found by its target selector. |
+
+## Feature flags
+
+| Term | What it is |
+| --- | --- |
+| **Feature flag** | A control that decides which visitors see a change, so you can run an A/B test or release in stages. The API type is `Feature`. |
+| **Weight** | The percentage of visitors that Picked allocates to a feature flag, from 0 to 100. |
+| **Allocation** | The act that puts a visitor in a feature flag. It happens when something first reads the bucket. |
+| **Bucket** | The value a feature flag resolves to for one visitor. |
+| **Exposure** | The moment a visitor enters a test. It is the same moment as the allocation. |
+| **Version** | A number on a feature flag that forms part of the cache key. It is not part of the allocation. |
+
+## Content
+
+| Term | What it is |
+| --- | --- |
+| **Page layout** | A reusable schema that sets which fields a Page can hold. The API type is `ContentModel`, and the dashboard list page is titled **Models**. |
+| **Step layout** | The same, for one Step inside a Flow. |
+| **Section** | A reusable schema fragment that you put inside one or more layouts. The API type is `ContentBlock`, and the dashboard list page is titled **Blocks**. |
+| **Content entry** | One instance of a layout, filled with real values. The dashboard list page is titled **Content**. |
+| **Asset** | A file that your content points at: an image, a video, a document, or HTML. |
+| **Asset library** | The project-level store that holds your assets. |
+| **Design system** | A set of shared design decisions for a project. |
+| **Content schema** | The set of fields that a layout or a section defines. |
+| **Asset version** | One file that somebody uploaded for an asset. The library keeps the earlier versions. |
+| **Validation error** | A report that one field in a content entry does not match its schema. It carries the path to the exact field. |
+
+## The SDK
+
+| Term | What it is |
+| --- | --- |
+| **Client** | The object that `createClient()` returns. It holds your configuration and runs the experiences. |
+| **Plugin** | A piece of behaviour that you pass to the `plugins` array of the client. |
+| **Component name** | The identifier that points an experience at a component in your application. |
+| **Adapter** | The function that lets the client render a framework component: `adaptReactComponent` or `adaptSvelteComponent`. |
+| **Slot** | A named mount point, rendered by `<ExperienceSlot name="…" />`. It maps to the `.picked-slot-<name>` selector. |
+| **Placement** | Where an experience renders against its target: `replace`, `before`, `prepend`, `append`, or `after`. |
+| **Target selector** | The selector that an experience renders into. |
+| **Snapshot** | The plain JSON that `serialize()` returns on your server, and that seeds the client in the browser. |
+| **Precondition** | A gate that decides whether Picked starts at all. |
+| **Visitor** | The person on your site. Picked gives each one a stable ID. A visitor is not a user. |
+| **Framework plugin** | The plugin that lets the client render a React or a Svelte component. |
+
+## APIs and analytics
+
+| Term | What it is |
+| --- | --- |
+| **Delivery API** | The public, anonymous, read-only REST API that serves your published configuration and content. |
+| **Management API** | The authenticated GraphQL API that controls your projects, experiences, and content. |
+| **Preview token** | A token that lets a Delivery API request read unpublished content. |
+| **PickedQL** | The SQL query language for your Picked analytics data. |
+| **Virtual table** | A table name in PickedQL, such as `metrics`, that maps to the real tables below it. |
+| **Virtual function** | A short function in PickedQL, such as `control_users()`, that expands to a full aggregate expression. |
+| **Dimension** | A column that PickedQL joins for you, such as `device_category`. |
+| **Report** | An embedded analytics dashboard or question, attached to a project. |
+
+## Tools
+
+| Term | What it is |
+| --- | --- |
+| **MCP connection** | A link between a Picked project and an AI tool, over the Model Context Protocol. The dashboard calls this **MCP connections**. |
+| **Integration** | A connection between Picked and another service. |
+| **Tag ID** | The identifier of a project, which the template for Google Tag Manager uses. |
+
+## Verbs
+
+The actions that Picked names, and what each one does. Where an API mutation uses the
+word exactly, the table says so.
+
+### You act on the dashboard
+
+| Verb | What it does |
+| --- | --- |
+| **Create** | Makes a new record. |
+| **Update** | Changes a record that exists. |
+| **Delete** | Removes a record permanently. You cannot reverse it. |
+| **Publish** | Makes an immutable snapshot of a workspace and serves it to your visitors. |
+| **Archive** | Moves a draft workspace out of the default list. It stays editable. |
+| **Unarchive** | Returns an archived workspace to the default list. |
+| **Duplicate** | Copies a workspace, and everything in it, into a new draft. |
+| **Restore** | Moves the live pointer of a project to an earlier version. It changes no data. |
+| **Preview** | Opens your site with an unpublished workspace applied, for your browser only. |
+| **Invite** | Sends an invitation to join an organization. |
+| **Revoke** | Invalidates an API key or an invitation immediately. |
+| **Install** | Connects an integration to your project. |
+
+### Picked acts on a visitor
+
+| Verb | What it does |
+| --- | --- |
+| **Allocate** | Puts a visitor in a feature flag. |
+| **Resolve** | Gives a feature flag its bucket for one visitor. The first read resolves it. |
+| **Decide** | Runs the `decide` function of a feature flag. |
+| **Evaluate** | Runs a condition against the current state. |
+| **Invoke** | Calls a predicate from inside a condition. |
+| **Serve** | Sends published content to a visitor. |
+
+### Your code acts on the SDK
+
+| Verb | What it does |
+| --- | --- |
+| **Register** | Adds a component, an action, a predicate, or a feature flag to the client. |
+| **Start** | Runs the client. `start()` is idempotent. |
+| **Adapt** | Wraps a framework component so the client can render it. |
+| **Serialize** | Builds a snapshot on your server, with `serialize()`. |
+| **Seed** | Gives the client a snapshot, so the first render matches the server. |
+| **Hydrate** | Takes over the server markup in the browser. |
+| **Render** | Puts a component into the page. |
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — how these parts fit together.
+- [Projects](/reference/dashboard/projects) — the dashboard surface.

package/dist/docs/reference/management-api/authentication.md

@@ -0,0 +1,74 @@
+---
+type: reference
+layout: docs
+---
+
+# Authentication
+
+The Picked API supports four ways to authenticate. They are a session from an email
+address and a password, an OAuth provider, a magic link, and an API key. This guide
+covers each one. It also covers how to control a session and how to use multi-factor
+authentication (MFA).
+
+## Use a session
+
+After the caller has a session, it puts the access token in the `Authorization`
+header of every request that needs authentication:
+
+```
+Authorization: Bearer <accessToken>
+```
+
+The `expiresAt` field of the session gives the time at which the access token
+expires. The caller must refresh the session before that time.
+
+### Authenticator assurance levels
+
+The session holds an `aal` field, and it gives the strength of the authentication:
+
+| Level | Meaning |
+|-------|---------|
+| `AAL1` | One factor: an email address and a password, OAuth, or a magic link |
+| `AAL2` | More than one factor: the user completed an MFA challenge |
+
+Some operations need `AAL2`. When a caller at `AAL1` tries one of them, the API
+returns an authorization error.
+
+## The mutations
+
+| Mutation | What it does |
+| --- | --- |
+| `sessionCreate` | Authenticates an email address and a password. Returns a session, or `requiresMfa`. |
+| `sessionRefresh` | Exchanges a refresh token for a new session. Needs no `Authorization` header. |
+| `accountCreate` | Creates an account. `metadata` takes any JSON. |
+| `accountVerifyEmail` | Completes email verification with the token from the email. |
+| `accountResendVerification` | Sends the verification email again. |
+| `oauthAuthorize` | Returns the authorization URL for a provider. Google is supported. |
+| `oauthCallback` | Exchanges an OAuth code for a session. |
+| `magicLinkSend` | Sends a sign-in link to an email address. |
+| `magicLinkVerify` | Exchanges a magic-link token for a session. |
+| `passwordResetSend` | Sends a password reset email. |
+| `passwordReset` | Completes a reset with the token from the email. |
+| `passwordUpdate` | Changes a password. Needs authentication. |
+| `mfaFactorEnroll` | Adds an MFA factor. A new factor is `UNVERIFIED`. |
+| `mfaChallengeSend` | Sends a code to the telephone number of the factor. |
+| `mfaChallengeVerify` | Verifies a challenge. Moves the session to `AAL2`. |
+| `mfaFactorUnenroll` | Removes an MFA factor. |
+| `apiKeyCreate` | Creates an API key. Only a user with a session can call it. |
+| `apiKeyRevoke` | Invalidates a key immediately. |
+
+## Credentials
+
+| Credential | Header |
+| --- | --- |
+| Session access token | `Authorization: Bearer <accessToken>` |
+| API key | `x-api-key: pk_live_abc123...` |
+
+## Related
+
+- [How to authenticate with a password](/how-to/authenticate-with-a-password)
+- [How to authenticate with OAuth](/how-to/authenticate-with-oauth)
+- [How to authenticate with a magic link](/how-to/authenticate-with-a-magic-link)
+- [How to set up MFA](/how-to/set-up-mfa)
+- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes)