@picked/client 0.0.70-next.6 → 0.0.70

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`.

package/dist/docs/api/error-handling.md

@@ -2,13 +2,16 @@
 layout: docs
 ---
 
-# Error handling
+# Errors
 
-The Picked API returns errors using the standard GraphQL error format. This guide covers the error response shape, all error codes, and practical strategies for handling errors.
+The Picked API returns an error in the standard GraphQL format. This guide covers the
+shape of an error response, every error code, and what your code must do with each
+one.
 
 ## Error response shape
 
-When an operation fails, the API returns an `errors` array in the response body. Each error object contains:
+When an operation fails, the API returns an `errors` array in the response body. Each
+error object holds these fields:
 
 ```json
 {
@@ -27,29 +30,31 @@ When an operation fails, the API returns an `errors` array in the response body.
 
 | Field | Description |
 |-------|-------------|
-| `message` | A human-readable error description. Suitable for logging but not for programmatic handling. |
-| `path` | The path to the field in the query that caused the error. |
-| `extensions.code` | A machine-readable error code. Use this for programmatic error handling. |
+| `message` | A description of the error that a person can read. Put it in your log. Do not write code against it. |
+| `path` | The path to the field in the query that made the error. |
+| `extensions.code` | An error code that a machine can read. Write your code against this field. |
 
-Multiple errors may appear in a single response. The `data` field may be `null` if the entire operation failed, or it may contain partial data if only some fields failed.
+One response can hold more than one error. The `data` field is `null` when the whole
+operation failed. It holds part of the data when only some fields failed.
 
 ## Authentication error codes
 
-These errors relate to session creation, account management, OAuth, magic links, password operations, and MFA. They map to the `AuthErrorCode` enum in the schema.
+These errors come from a session, an account, OAuth, a magic link, a password
+operation, or MFA. They match the `AuthErrorCode` enum in the schema.
 
 | Code | Description |
 |------|-------------|
-| `INVALID_CREDENTIALS` | The email/password combination is incorrect. |
-| `EMAIL_NOT_CONFIRMED` | The account exists but the email address has not been verified. See [Authentication](/api/authentication#email-verification). |
-| `USER_NOT_FOUND` | No account exists with the provided email address. |
-| `USER_ALREADY_EXISTS` | An account with this email already exists. Returned during account creation. |
-| `WEAK_PASSWORD` | The provided password does not meet strength requirements. |
-| `INVALID_TOKEN` | The token (verification, reset, or magic link) is invalid or malformed. |
-| `TOKEN_EXPIRED` | The token has expired. The caller should request a new one. |
-| `MFA_CHALLENGE_FAILED` | The MFA verification code is incorrect. |
-| `MFA_FACTOR_NOT_FOUND` | The specified MFA factor does not exist or does not belong to the caller. |
-| `OAUTH_PROVIDER_ERROR` | An error occurred communicating with the OAuth provider (e.g., Google). |
-| `RATE_LIMITED` | Too many requests in a short period. The caller should wait and retry. |
+| `INVALID_CREDENTIALS` | The email address and the password do not match. |
+| `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/api/authentication#verify-an-email-address). |
+| `USER_NOT_FOUND` | There is no account with that email address. |
+| `USER_ALREADY_EXISTS` | An account with that email address is there already. The API returns this when you create an account. |
+| `WEAK_PASSWORD` | The password is not strong enough. |
+| `INVALID_TOKEN` | The token is invalid or malformed. This covers a verification token, a reset token, and a magic link token. |
+| `TOKEN_EXPIRED` | The token expired. Ask for a new one. |
+| `MFA_CHALLENGE_FAILED` | The MFA verification code is not correct. |
+| `MFA_FACTOR_NOT_FOUND` | That MFA factor is not there, or it belongs to another caller. |
+| `OAUTH_PROVIDER_ERROR` | The exchange with the OAuth provider, such as Google, failed. |
+| `RATE_LIMITED` | Too many requests in a short period. Wait, then try again. |
 
 ### Example: invalid credentials
 
@@ -76,16 +81,18 @@ These errors relate to session creation, account management, OAuth, magic links,
 
 ## Authorization error codes
 
-Authorization errors occur when the caller lacks the required [scope](./authorization-and-scopes.md) for an operation.
+An authorization error happens when the caller does not hold the
+[scope](./authorization-and-scopes.md) that an operation needs.
 
 | Code | Description |
 |------|-------------|
-| `UNAUTHORIZED` | No valid authentication was provided. The request is missing the `Authorization` header or the `x-api-key` header, or the token/key is invalid. |
-| `FORBIDDEN` | The caller is authenticated but does not have the required scope for the operation. |
+| `UNAUTHORIZED` | The request carries no valid authentication. It has no `Authorization` header and no `x-api-key` header, or the token is invalid. |
+| `FORBIDDEN` | The caller is authenticated, but it does not hold the scope that the operation needs. |
 
-### Example: insufficient scope
+### Example: the scope is not enough
 
-A caller with only `organization/read` attempting to delete an organization receives:
+A caller that holds `organization/read` only tries to delete an organization. It
+receives this:
 
 ```json
 {
@@ -106,52 +113,53 @@ A caller with only `organization/read` attempting to delete an organization rece
 
 ## Organization, member, and invitation error codes
 
-These errors relate to organization management, member operations, and invitation workflows. They map to the `ErrorCode` enum in the schema.
+These errors come from an organization, a member operation, or an invitation. They
+match the `ErrorCode` enum in the schema.
 
 ### Organization errors
 
 | Code | Description |
 |------|-------------|
-| `ORGANIZATION_NOT_FOUND` | The specified organization does not exist or the caller does not have access to it. |
-| `ORGANIZATION_ALREADY_EXISTS` | An organization with this name already exists. |
-| `SLUG_ALREADY_EXISTS` | The requested slug is already in use by another organization. |
-| `INVALID_SLUG` | The slug contains invalid characters. Slugs must be lowercase alphanumeric with hyphens. |
+| `ORGANIZATION_NOT_FOUND` | That organization is not there, or the caller cannot reach it. |
+| `ORGANIZATION_ALREADY_EXISTS` | An organization with that name is there already. |
+| `SLUG_ALREADY_EXISTS` | Another organization uses that slug already. |
+| `INVALID_SLUG` | The slug holds an invalid character. A slug takes lowercase letters, digits, and hyphens only. |
 
 ### Member errors
 
 | Code | Description |
 |------|-------------|
-| `MEMBER_NOT_FOUND` | The specified user is not a member of the organization. |
-| `MEMBER_ALREADY_EXISTS` | The user is already a member of the organization. |
-| `CANNOT_REMOVE_PRIMARY_OWNER` | The primary owner of an organization cannot be removed. |
-| `CANNOT_CHANGE_OWN_ROLE` | A member cannot change their own role. Another owner must perform this action. |
+| `MEMBER_NOT_FOUND` | That user is not a member of the organization. |
+| `MEMBER_ALREADY_EXISTS` | The user is a member of the organization already. |
+| `CANNOT_REMOVE_PRIMARY_OWNER` | You cannot remove the primary owner of an organization. |
+| `CANNOT_CHANGE_OWN_ROLE` | A member cannot change the role of that same member. Another owner must do it. |
 
 ### Invitation errors
 
 | Code | Description |
 |------|-------------|
-| `INVITATION_NOT_FOUND` | The specified invitation does not exist. |
-| `INVITATION_EXPIRED` | The invitation has expired and can no longer be accepted. |
-| `INVITATION_ALREADY_ACCEPTED` | The invitation has already been accepted. |
+| `INVITATION_NOT_FOUND` | That invitation is not there. |
+| `INVITATION_EXPIRED` | The invitation expired. Nobody can accept it now. |
+| `INVITATION_ALREADY_ACCEPTED` | Somebody accepted the invitation already. |
 
 ### Project errors
 
 | Code | Description |
 |------|-------------|
-| `PROJECT_NOT_FOUND` | The specified project does not exist or the caller does not have access. |
+| `PROJECT_NOT_FOUND` | That project is not there, or the caller cannot reach it. |
 
 ### General errors
 
 | Code | Description |
 |------|-------------|
-| `VALIDATION_ERROR` | The input failed validation. Check the `message` field for details about which field is invalid. |
-| `INTERNAL_ERROR` | An unexpected server error occurred. Retry the request or contact support if the issue persists. |
+| `VALIDATION_ERROR` | The input failed a validation rule. Read the `message` field to learn which field is invalid. |
+| `INTERNAL_ERROR` | The server met an unexpected error. Try the request again. Contact support when the error continues. |
 
-## Handling errors in practice
+## What your code must do
 
-### Check for errors first
+### Look for an error first
 
-Every response should be checked for the presence of an `errors` array before processing `data`:
+Check every response for an `errors` array before you read `data`:
 
 ```javascript
 const response = await fetch('/graphql', {
@@ -171,41 +179,49 @@ if (result.errors) {
 
     switch (code) {
       case 'UNAUTHORIZED':
-        // Redirect to login
+        // Send the user to the sign-in page.
         break;
       case 'FORBIDDEN':
-        // Show a permissions error
+        // Show a permissions error.
         break;
       case 'RATE_LIMITED':
-        // Wait and retry
+        // Wait, then try again.
         break;
       default:
-        // Log or display the error message
+        // Put the message in the log, or show it.
         console.error(error.message);
     }
   }
 }
 ```
 
-### Refresh expired tokens
+### Refresh a token that expired
 
-If a request returns `UNAUTHORIZED` and the caller has a refresh token, attempt a [session refresh](/api/authentication#session-refresh) before treating it as a login failure:
+A request can return `UNAUTHORIZED` while the caller holds a refresh token. Try a
+[session refresh](/api/authentication#refresh-a-session) first. Do not treat it as a
+failure to sign in:
 
 ```javascript
 if (code === 'UNAUTHORIZED' && refreshToken) {
   const refreshResult = await sessionRefresh(refreshToken);
   if (refreshResult.session) {
-    // Retry the original request with the new access token
+    // Try the first request again with the new access token.
   } else {
-    // Redirect to login
+    // Send the user to the sign-in page.
   }
 }
 ```
 
-### Handle partial data
+### Read data that is only part complete
 
-GraphQL can return partial data alongside errors. For example, a query that fetches an organization and its members might succeed for the organization but fail for the members if the caller lacks `organization_members/read`. In this case, the response contains both `data` (with the organization) and `errors` (for the members field). Always check both.
+GraphQL can return part of the data together with an error. Take a query that reads
+an organization and its members. It can succeed for the organization and fail for the
+members, when the caller does not hold `organization_members/read`. The response then
+holds `data` with the organization, and `errors` for the members field. Always read
+both.
 
-### Retry transient failures
+### Try again after a transient failure
 
-`INTERNAL_ERROR` and `RATE_LIMITED` are transient. For `RATE_LIMITED`, implement exponential backoff before retrying. For `INTERNAL_ERROR`, a single retry is usually sufficient.
+`INTERNAL_ERROR` and `RATE_LIMITED` are both transient. For `RATE_LIMITED`, use an
+exponential backoff before you try again. For `INTERNAL_ERROR`, one more try is
+usually enough.

package/dist/docs/api/index.md

@@ -2,17 +2,21 @@
 layout: docs
 ---
 
-# Getting started
+# Start here
 
-This guide walks you through your first interactions with the Picked GraphQL API, from sending a simple ping to making authenticated queries and mutations.
+This guide takes you through your first calls to the Picked GraphQL API. It starts
+with a ping and ends with an authenticated query and mutation.
 
 :::note
-This reference covers the authenticated GraphQL management API. To serve your published config and page content to your app, use the public, read-only [Delivery API](/delivery-api) instead.
+This reference covers the GraphQL API that needs authentication. To serve your
+published options and page content to your application, use the public
+[Delivery API](/delivery-api), which is read-only.
 :::
 
 ## Playground
 
-Explore the API and run queries interactively in the [GraphQL Playground](https://api.picked.app/api/graphql).
+Read the API and run a query in the
+[GraphQL Playground](https://api.picked.app/api/graphql).
 
 ## API endpoint
 
@@ -22,7 +26,8 @@ All requests go to a single endpoint:
 POST https://api.picked.app/api/graphql
 ```
 
-Every request must use the `POST` method with a JSON body containing a `query` field and an optional `variables` field:
+Every request must use the `POST` method. The JSON body must hold a `query` field,
+and it can also hold a `variables` field:
 
 ```json
 {
@@ -41,7 +46,8 @@ curl -X POST https://api.picked.app/api/graphql \
 
 ## Ping the API
 
-Verify that the API is reachable with the `ping` query. This query does not require authentication.
+Check that the API is reachable with the `ping` query. This query needs no
+authentication.
 
 ```graphql
 query {
@@ -59,11 +65,12 @@ Response:
 }
 ```
 
-If you receive this response, the API is up and ready.
+This response means that the API is ready.
 
 ## Authenticate
 
-Most operations require an access token. You obtain one by creating a session with your email and password.
+Most operations need an access token. To get one, create a session with your email
+address and your password.
 
 ```graphql
 mutation {
@@ -81,7 +88,8 @@ mutation {
 }
 ```
 
-A successful response returns a `Session` containing an `accessToken` and a `refreshToken`:
+A successful response returns a `Session` with an `accessToken` and a
+`refreshToken`:
 
 ```json
 {
@@ -98,9 +106,12 @@ A successful response returns a `Session` containing an `accessToken` and a `ref
 }
 ```
 
-If `requiresMfa` is `true`, you need to complete the MFA challenge before receiving a session. See the [Authentication](./authentication.md) guide for details.
+When `requiresMfa` is `true`, you must complete the MFA challenge before you receive
+a session. See the [Authentication](./authentication.md) guide.
 
-For server-to-server integrations, prefer [API key authentication](/api/authentication#api-key-authentication) over session tokens.
+For a server-to-server integration, use
+[API key authentication](/api/authentication#api-key-authentication) and not a
+session token.
 
 ## Make an authenticated query
 
@@ -110,7 +121,8 @@ Pass the access token in the `Authorization` header as a Bearer token:
 Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
 ```
 
-Now you can query resources that require authentication. For example, fetch your user profile:
+You can now query a resource that needs authentication. This example reads your user
+profile:
 
 ```graphql
 query {
@@ -132,7 +144,8 @@ query {
 
 ## Make a mutation
 
-Mutations follow the same pattern: send a `POST` request with the `Authorization` header. For example, create an organization:
+A mutation follows the same pattern. Send a `POST` request with the `Authorization`
+header. This example creates an organization:
 
 ```graphql
 mutation {
@@ -165,11 +178,14 @@ Response:
 }
 ```
 
-Every mutation accepts an `input` argument and returns a payload object. The payload contains the created or updated resource on success, or errors in the top-level `errors` array on failure.
+Every mutation takes an `input` argument and returns a payload object. On success the
+payload holds the resource that the mutation created or updated. On failure the
+`errors` array at the top level holds the errors.
 
-## Error handling basics
+## Errors
 
-When something goes wrong, the API returns errors in the standard GraphQL `errors` array:
+When something goes wrong, the API returns the errors in the standard GraphQL
+`errors` array:
 
 ```json
 {
@@ -185,13 +201,16 @@ When something goes wrong, the API returns errors in the standard GraphQL `error
 }
 ```
 
-Check the `extensions.code` field for a machine-readable error code you can use to handle specific failures programmatically. See the [Error Handling](./error-handling.md) guide for the full list of error codes.
+Read the `extensions.code` field. It holds an error code that your code can act on.
+See the [Errors](./error-handling.md) guide for the full list of codes.
 
 ## Next steps
 
-Now that you can authenticate and make requests, explore these guides to go deeper:
+You can now authenticate and make a request. These guides go into more detail:
 
-- [Authentication](./authentication.md) — email/password, OAuth, magic links, MFA, API keys, and session management
-- [Authorization and Scopes](./authorization-and-scopes.md) — understand what each role can access and how scopes control permissions
-- [Pagination](./pagination.md) — navigate large result sets with cursor-based pagination
-- [Error Handling](./error-handling.md) — handle every error code the API can return
+- [Authentication](./authentication.md) — an email address and a password, OAuth,
+  magic links, MFA, API keys, and how to control a session.
+- [Authorization and Scopes](./authorization-and-scopes.md) — what each role can
+  reach, and how a scope controls a permission.
+- [Pagination](./pagination.md) — how to move through a large result with a cursor.
+- [Errors](./error-handling.md) — every error code that the API can return.