@picked/client 0.0.70-next.6 → 0.0.71-next.1

package/dist/docs/api/authentication.md

@@ -4,11 +4,15 @@ layout: docs
 
 # Authentication
 
-The Picked API supports multiple authentication methods: email/password sessions, OAuth providers, magic links, and API keys. This guide covers each method and explains how to manage sessions and multi-factor authentication (MFA).
+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).
 
-## Email and password login
+## Sign in with an email address and a password
 
-The `sessionCreate` mutation authenticates a user with email and password and returns a session.
+The `sessionCreate` mutation authenticates a user from an email address and a
+password. It returns a session.
 
 ```graphql
 mutation {
@@ -36,13 +40,16 @@ mutation {
 }
 ```
 
-If the user has MFA enabled, the response sets `requiresMfa` to `true` and returns the enrolled `mfaFactors`. The caller must complete an MFA challenge before receiving a fully authenticated session. See the [MFA](#multi-factor-authentication-mfa) section below.
+When the user has MFA on, the response sets `requiresMfa` to `true` and returns the
+`mfaFactors` of that user. The caller must then complete an MFA challenge before it
+receives a full session. See [MFA](#multi-factor-authentication-mfa) below.
 
-If MFA is not enabled, the response includes a `session` with an `accessToken`, a `refreshToken`, and an `expiresAt` timestamp.
+When MFA is off, the response holds a `session` with an `accessToken`, a
+`refreshToken`, and an `expiresAt` timestamp.
 
-## Account creation
+## Create an account
 
-New accounts are created with the `accountCreate` mutation:
+The `accountCreate` mutation creates a new account:
 
 ```graphql
 mutation {
@@ -63,11 +70,14 @@ mutation {
 }
 ```
 
-The `metadata` field is optional and accepts arbitrary JSON for storing profile information. When email verification is required, the returned session is `null` until the email is verified.
+The `metadata` field is optional. It takes any JSON, and you can hold profile
+information in it. When the account needs email verification, the session in the
+response is `null` until the user verifies the email address.
 
-## Email verification
+## Verify an email address
 
-After account creation, the user receives a verification email containing a token. The `accountVerifyEmail` mutation completes verification:
+After you create the account, the user receives a verification email with a token.
+The `accountVerifyEmail` mutation completes the verification:
 
 ```graphql
 mutation {
@@ -83,7 +93,7 @@ mutation {
 }
 ```
 
-If the verification email needs to be resent:
+To send the verification email again:
 
 ```graphql
 mutation {
@@ -95,11 +105,11 @@ mutation {
 }
 ```
 
-## OAuth flow (Google)
+## The OAuth flow with Google
 
 The API supports Google as an OAuth provider. The flow has two steps.
 
-### Step 1: Get the authorization URL
+### Step 1: get the authorization URL
 
 ```graphql
 mutation {
@@ -113,9 +123,11 @@ mutation {
 }
 ```
 
-The caller redirects the user to the returned `url`. After the user authenticates with Google, they are redirected back to a URL on the same dashboard deployment with a `code` parameter, where the caller exchanges it for a session.
+The caller sends the user to the `url` in the response. The user authenticates with
+Google. Google then sends the user back to a URL on the same dashboard deployment,
+with a `code` parameter. The caller exchanges that code for a session.
 
-### Step 2: Exchange the code for a session
+### Step 2: exchange the code for a session
 
 ```graphql
 mutation {
@@ -134,7 +146,7 @@ mutation {
 
 ## Magic links
 
-Magic links allow passwordless authentication via email.
+A magic link authenticates a user through an email address, with no password.
 
 ### Send a magic link
 
@@ -149,7 +161,7 @@ mutation {
 }
 ```
 
-The user receives an email containing a link with a token.
+The user receives an email with a link, and the link holds a token.
 
 ### Verify the magic link
 
@@ -167,11 +179,11 @@ mutation {
 }
 ```
 
-## Password management
+## Passwords
 
-### Reset a forgotten password
+### Reset a password
 
-Send a password reset email:
+Send an email to reset the password:
 
 ```graphql
 mutation {
@@ -184,7 +196,7 @@ mutation {
 }
 ```
 
-Complete the reset with the token from the email:
+Complete the reset with the token from that email:
 
 ```graphql
 mutation {
@@ -201,9 +213,9 @@ mutation {
 }
 ```
 
-### Update an existing password
+### Change a password
 
-This mutation requires authentication:
+This mutation needs authentication:
 
 ```graphql
 mutation {
@@ -218,9 +230,11 @@ mutation {
 
 ## Multi-factor authentication (MFA)
 
-MFA adds a second layer of security using phone-based verification. The API supports enrolling, challenging, verifying, and unenrolling MFA factors. All MFA mutations require authentication.
+MFA adds a second layer of security, and it uses a telephone to verify the user. The
+API can add an MFA factor, send a challenge, verify a challenge, and remove a factor.
+Every MFA mutation needs authentication.
 
-### Enroll a factor
+### Add a factor
 
 ```graphql
 mutation {
@@ -238,7 +252,7 @@ mutation {
 }
 ```
 
-A newly enrolled factor has a status of `UNVERIFIED` until confirmed via a challenge.
+A new factor has the status `UNVERIFIED` until a challenge confirms it.
 
 ### Send a challenge
 
@@ -252,7 +266,7 @@ mutation {
 }
 ```
 
-This sends a verification code to the enrolled phone number.
+This sends a verification code to the telephone number of the factor.
 
 ### Verify the challenge
 
@@ -272,9 +286,10 @@ mutation {
 }
 ```
 
-On success, the session is upgraded to Authenticator Assurance Level `AAL2`. The factor status changes to `VERIFIED`.
+On success, the session moves to Authenticator Assurance Level `AAL2`. The status of
+the factor changes to `VERIFIED`.
 
-### Unenroll a factor
+### Remove a factor
 
 ```graphql
 mutation {
@@ -286,30 +301,34 @@ mutation {
 }
 ```
 
-## Using a session
+## Use a session
 
-After obtaining a session, the caller includes the access token in the `Authorization` header of every authenticated request:
+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 on the session indicates when the access token expires. The caller should refresh the session before the token expires.
+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 includes an `aal` field indicating the authentication strength:
+The session holds an `aal` field, and it gives the strength of the authentication:
 
 | Level | Meaning |
 |-------|---------|
-| `AAL1` | Single-factor authentication (email/password, OAuth, or magic link) |
-| `AAL2` | Multi-factor authentication (MFA challenge completed) |
+| `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 may require `AAL2`. If a caller with `AAL1` attempts such an operation, the API returns an authorization error.
+Some operations need `AAL2`. When a caller at `AAL1` tries one of them, the API
+returns an authorization error.
 
-## Session refresh
+## Refresh a session
 
-Access tokens are short-lived. The `sessionRefresh` mutation exchanges a refresh token for a new session:
+An access token has a short life. The `sessionRefresh` mutation exchanges a refresh
+token for a new session:
 
 ```graphql
 mutation {
@@ -325,11 +344,14 @@ mutation {
 }
 ```
 
-The response includes a new `accessToken` and a new `refreshToken`. The previous refresh token is invalidated. This mutation does not require the `Authorization` header.
+The response holds a new `accessToken` and a new `refreshToken`. The API invalidates
+the earlier refresh token. This mutation needs no `Authorization` header.
 
 ## API key authentication
 
-API keys provide long-lived, scoped access to the API. They are typically used for server-to-server integrations and automated workflows.
+An API key gives access to the API for a long time, inside a set of scopes. Most
+callers use an API key for a server-to-server integration or for an automated
+workflow.
 
 To authenticate with an API key, include it in the `x-api-key` header:
 
@@ -337,13 +359,16 @@ To authenticate with an API key, include it in the `x-api-key` header:
 x-api-key: pk_live_abc123...
 ```
 
-API keys are scoped to an organization and optionally to a specific project. They carry a defined set of [authorization scopes](./authorization-and-scopes.md) that determine which operations the key can perform.
+An API key belongs to an organization, and it can also belong to one project. It
+carries a set of [authorization scopes](./authorization-and-scopes.md), and those
+scopes decide which operations the key can do.
 
-See [API Keys](/api-keys) for managing keys from the dashboard UI.
+See [API Keys](/api-keys) for how to control a key from the dashboard.
 
-### Creating an API key
+### Create an API key
 
-The `apiKeyCreate` mutation creates a new API key. This mutation is only available to session-authenticated users (not other API keys):
+The `apiKeyCreate` mutation creates a new API key. Only a user with a session can
+call it. Another API key cannot:
 
 ```graphql
 mutation {
@@ -358,11 +383,13 @@ mutation {
 }
 ```
 
-The full API key string is returned only once in the response. Store it securely; it cannot be retrieved again.
+The response holds the full API key string one time only. Keep it in a secure place, because
+you cannot read it again.
 
-The requested scopes must be a subset of the creating user's scopes. See [Authorization and Scopes](./authorization-and-scopes.md) for more details.
+The scopes that you ask for must all be scopes of the user who creates the key. See
+[Authorization and Scopes](./authorization-and-scopes.md) for more detail.
 
-### Revoking an API key
+### Revoke an API key
 
 ```graphql
 mutation {
@@ -373,4 +400,4 @@ mutation {
 }
 ```
 
-Revoked keys are immediately invalidated and cannot be used for further requests.
+The API invalidates a revoked key immediately. No later request can use it.

package/dist/docs/api/authorization-and-scopes.md

@@ -4,11 +4,14 @@ layout: docs
 
 # Authorization and scopes
 
-The Picked API uses a scope-based authorization model. Every authenticated caller (session user or API key) carries a set of scopes that determine which operations they can perform. This guide explains the scope system, roles, and how permissions are resolved.
+The Picked API controls access with scopes. Every authenticated caller carries a set
+of scopes, and those scopes decide which operations the caller can do. A caller is
+either a user with a session or an API key. This guide covers the scopes, the roles,
+and how the API resolves a permission.
 
-## Scope naming format
+## The format of a scope name
 
-Scopes follow the `entity/action` convention:
+A scope has the form `entity/action`:
 
 ```
 organization/read
@@ -16,83 +19,87 @@ organization_members/create
 organization_projects/delete
 ```
 
-- **entity** — a lowercase name using underscores for multi-word entities (e.g., `organization_members`, `organization_api_keys`)
-- **action** — one of `create`, `read`, `update`, or `delete`
+- **entity** — a lowercase name. It uses an underscore between words, as in
+  `organization_members` and `organization_api_keys`.
+- **action** — one of `create`, `read`, `update`, or `delete`.
 
-In the GraphQL schema, scopes are represented as the `Scope` enum using uppercase with underscores (e.g., `ORGANIZATION_READ`, `ORGANIZATION_MEMBERS_CREATE`). Both formats refer to the same scope.
+The GraphQL schema holds the scopes in the `Scope` enum. There they are uppercase
+with an underscore between words, as in `ORGANIZATION_READ` and
+`ORGANIZATION_MEMBERS_CREATE`. The two forms name the same scope.
 
 ## Full scope list
 
-The following scopes are available:
+These are the scopes:
 
 ### Organization
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization/create` | `ORGANIZATION_CREATE` | Create new organizations |
-| `organization/read` | `ORGANIZATION_READ` | View organization details |
-| `organization/update` | `ORGANIZATION_UPDATE` | Update organization name, slug, and settings |
+| `organization/create` | `ORGANIZATION_CREATE` | Create an organization |
+| `organization/read` | `ORGANIZATION_READ` | Read the detail of an organization |
+| `organization/update` | `ORGANIZATION_UPDATE` | Update the name, the slug, and the settings of an organization |
 | `organization/delete` | `ORGANIZATION_DELETE` | Delete an organization |
 
 ### Organization members
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_members/create` | `ORGANIZATION_MEMBERS_CREATE` | Add members to an organization |
-| `organization_members/read` | `ORGANIZATION_MEMBERS_READ` | View organization member list |
-| `organization_members/update` | `ORGANIZATION_MEMBERS_UPDATE` | Update member roles |
-| `organization_members/delete` | `ORGANIZATION_MEMBERS_DELETE` | Remove members from an organization |
+| `organization_members/create` | `ORGANIZATION_MEMBERS_CREATE` | Add a member to an organization |
+| `organization_members/read` | `ORGANIZATION_MEMBERS_READ` | Read the member list of an organization |
+| `organization_members/update` | `ORGANIZATION_MEMBERS_UPDATE` | Update the role of a member |
+| `organization_members/delete` | `ORGANIZATION_MEMBERS_DELETE` | Remove a member from an organization |
 
 ### Organization invitations
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_invitations/create` | `ORGANIZATION_INVITATIONS_CREATE` | Send invitations to join an organization |
-| `organization_invitations/read` | `ORGANIZATION_INVITATIONS_READ` | View pending invitations |
-| `organization_invitations/delete` | `ORGANIZATION_INVITATIONS_DELETE` | Revoke pending invitations |
+| `organization_invitations/create` | `ORGANIZATION_INVITATIONS_CREATE` | Send an invitation to join an organization |
+| `organization_invitations/read` | `ORGANIZATION_INVITATIONS_READ` | Read the invitations that wait for an answer |
+| `organization_invitations/delete` | `ORGANIZATION_INVITATIONS_DELETE` | Revoke an invitation that waits for an answer |
 
 ### Organization projects
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_projects/create` | `ORGANIZATION_PROJECTS_CREATE` | Create new projects |
-| `organization_projects/read` | `ORGANIZATION_PROJECTS_READ` | View project details |
-| `organization_projects/update` | `ORGANIZATION_PROJECTS_UPDATE` | Update project settings |
-| `organization_projects/delete` | `ORGANIZATION_PROJECTS_DELETE` | Delete projects |
+| `organization_projects/create` | `ORGANIZATION_PROJECTS_CREATE` | Create a project |
+| `organization_projects/read` | `ORGANIZATION_PROJECTS_READ` | Read the detail of a project |
+| `organization_projects/update` | `ORGANIZATION_PROJECTS_UPDATE` | Update the settings of a project |
+| `organization_projects/delete` | `ORGANIZATION_PROJECTS_DELETE` | Delete a project |
 
 ### Organization API keys
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_api_keys/create` | `ORGANIZATION_API_KEYS_CREATE` | Create new API keys |
-| `organization_api_keys/read` | `ORGANIZATION_API_KEYS_READ` | View API keys (prefix only, not the full key) |
-| `organization_api_keys/delete` | `ORGANIZATION_API_KEYS_DELETE` | Revoke API keys |
+| `organization_api_keys/create` | `ORGANIZATION_API_KEYS_CREATE` | Create an API key |
+| `organization_api_keys/read` | `ORGANIZATION_API_KEYS_READ` | Read the API keys. This gives the prefix only, and not the full key. |
+| `organization_api_keys/delete` | `ORGANIZATION_API_KEYS_DELETE` | Revoke an API key |
 
 ### Organization integrations
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_integrations/create` | `ORGANIZATION_INTEGRATIONS_CREATE` | Set up new integrations |
-| `organization_integrations/read` | `ORGANIZATION_INTEGRATIONS_READ` | View integration configurations |
-| `organization_integrations/update` | `ORGANIZATION_INTEGRATIONS_UPDATE` | Modify integration settings |
-| `organization_integrations/delete` | `ORGANIZATION_INTEGRATIONS_DELETE` | Remove integrations |
+| `organization_integrations/create` | `ORGANIZATION_INTEGRATIONS_CREATE` | Set up an integration |
+| `organization_integrations/read` | `ORGANIZATION_INTEGRATIONS_READ` | Read the options of an integration |
+| `organization_integrations/update` | `ORGANIZATION_INTEGRATIONS_UPDATE` | Change the settings of an integration |
+| `organization_integrations/delete` | `ORGANIZATION_INTEGRATIONS_DELETE` | Remove an integration |
 
 ### Organization reports
 
 | Scope | GraphQL Enum | Description |
 |-------|-------------|-------------|
-| `organization_reports/create` | `ORGANIZATION_REPORTS_CREATE` | Create new reports |
-| `organization_reports/read` | `ORGANIZATION_REPORTS_READ` | View reports |
-| `organization_reports/update` | `ORGANIZATION_REPORTS_UPDATE` | Update report settings |
-| `organization_reports/delete` | `ORGANIZATION_REPORTS_DELETE` | Delete reports |
+| `organization_reports/create` | `ORGANIZATION_REPORTS_CREATE` | Create a report |
+| `organization_reports/read` | `ORGANIZATION_REPORTS_READ` | Read a report |
+| `organization_reports/update` | `ORGANIZATION_REPORTS_UPDATE` | Update the settings of a report |
+| `organization_reports/delete` | `ORGANIZATION_REPORTS_DELETE` | Delete a report |
 
 ## Roles
 
-Organization members are assigned one of two roles:
+Each member of an organization holds one of two roles:
 
 ### Owner
 
-Owners have full control within their organization. Their default scopes include:
+An owner has full control inside the organization. These are the default scopes of an
+owner:
 
 - All `organization/*` scopes (`read`, `update`, `delete`)
 - All `organization_members/*` scopes
@@ -104,7 +111,8 @@ Owners have full control within their organization. Their default scopes include
 
 ### Member
 
-Members have broad access but cannot delete the organization or manage other members. Their default scopes include:
+A member can reach most things, but cannot delete the organization and cannot control
+another member. These are the default scopes of a member:
 
 - `organization/read`, `organization/update`
 - `organization_members/read`
@@ -114,7 +122,7 @@ Members have broad access but cannot delete the organization or manage other mem
 - All `organization_integrations/*` scopes
 - `organization_reports/read`
 
-The key differences between owner and member:
+These are the differences between an owner and a member:
 
 | Capability | Owner | Member |
 |-----------|-------|--------|
@@ -123,24 +131,30 @@ The key differences between owner and member:
 | Remove members | Yes | No |
 | Update member roles | Yes | No |
 | Revoke invitations | Yes | No |
-| Manage projects and integrations | Yes | Yes |
-| Manage API keys | Yes | Yes |
-| View reports | Yes | Yes |
+| Control projects and integrations | Yes | Yes |
+| Control API keys | Yes | Yes |
+| Read reports | Yes | Yes |
 
 ## How scopes are resolved
 
-When an authenticated request reaches the API, the authorization system resolves scopes as follows:
+When an authenticated request reaches the API, the API resolves the scopes like this:
 
-1. **Session-authenticated users** — the API looks up the caller's role within the target organization and assigns the default scopes for that role.
-2. **API key requests** — the API uses the scopes that were assigned to the key at creation time. These scopes are always a subset of the creating user's scopes.
+1. **A user with a session** — the API finds the role of that caller in the target
+   organization. It then gives the caller the default scopes of that role.
+2. **A request with an API key** — the API uses the scopes that the key received when
+   somebody created it. Those scopes are always scopes of the user who created the
+   key.
 
-For operations that target a specific organization (most queries and mutations), the caller must have the required scope within that organization. For root-level operations like `organizationCreate`, the scope is resolved at the account level.
+Most queries and mutations point at one organization. For those, the caller must hold
+the scope inside that organization. For a root-level operation such as
+`organizationCreate`, the API resolves the scope at the account level.
 
-If the caller lacks the required scope, the API returns an authorization error with a `FORBIDDEN` code. See [Error Handling](./error-handling.md) for details.
+When the caller does not hold the scope that an operation needs, the API returns an
+authorization error with the code `FORBIDDEN`. See [Errors](./error-handling.md).
 
 ## Operations and required scopes
 
-The following table maps common operations to the scopes they require:
+This table gives the scope that each common operation needs:
 
 ### Queries
 
@@ -192,7 +206,7 @@ Some mutations do not require organization-level scopes because they operate on
 | `organizationInvitationAccept` / `organizationInvitationDecline` | Authenticated session (no specific scope) |
 | `mfaFactorEnroll` / `mfaChallengeSend` / `mfaChallengeVerify` / `mfaFactorUnenroll` | Authenticated session (no specific scope) |
 
-## Querying scopes
+## Read your scopes
 
 ### Root-level scopes
 
@@ -259,4 +273,6 @@ Response:
 }
 ```
 
-This is useful for building UIs that adapt based on the caller's permissions — for example, hiding a "Delete Organization" button when the caller lacks `ORGANIZATION_DELETE`.
+Use this to build a UI that changes with the permissions of the caller. An example is
+a **Delete Organization** button that the UI hides when the caller does not hold
+`ORGANIZATION_DELETE`.