picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/external-api.md

@@ -6,13 +6,14 @@ generated: true
 
 # External api schema
 
-The operations and types that `external-api.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `externalApi`
 
-Fetch a single external API by ID, or null if it does not exist. Requires authentication and `ORGANIZATION_INTEGRATIONS_READ` on its project.
+Reads an external API. Null when it does not exist.
+Scope: `ORGANIZATION_INTEGRATIONS_READ`.
 
 ```graphql
 externalApi(input: ExternalApiInput!): ExternalApi @auth
@@ -22,7 +23,8 @@ externalApi(input: ExternalApiInput!): ExternalApi @auth
 
 ### `externalApiCreate`
 
-Register an external API to a project. Requires a user context and `ORGANIZATION_INTEGRATIONS_CREATE`; API keys are rejected.
+Creates an external API in a project, with an optional credential.
+Scope: `ORGANIZATION_INTEGRATIONS_CREATE`.
 
 ```graphql
 externalApiCreate(input: ExternalApiCreateInput!): ExternalApiCreatePayload! @auth(only: USER)
@@ -30,7 +32,8 @@ externalApiCreate(input: ExternalApiCreateInput!): ExternalApiCreatePayload! @au
 
 ### `externalApiUpdate`
 
-Rename an external API. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected.
+Updates the name of an external API. To change the origin, delete it and create another.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 externalApiUpdate(input: ExternalApiUpdateInput!): ExternalApiUpdatePayload! @auth(only: USER)
@@ -38,7 +41,8 @@ externalApiUpdate(input: ExternalApiUpdateInput!): ExternalApiUpdatePayload! @au
 
 ### `externalApiAuthHeaderSet`
 
-Set or replace the single static auth header on an external API, removing an OAuth2 credential it holds. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected.
+Sets the static auth header of an external API, and removes any OAuth2 credential.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 externalApiAuthHeaderSet(input: ExternalApiAuthHeaderSetInput!): ExternalApiAuthHeaderSetPayload! @auth(only: USER)
@@ -46,7 +50,9 @@ externalApiAuthHeaderSet(input: ExternalApiAuthHeaderSetInput!): ExternalApiAuth
 
 ### `externalApiAuthHeaderClear`
 
-Remove the static auth header from an external API. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected.
+Removes the static auth header of an external API. An external API with no static header is
+unchanged.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 externalApiAuthHeaderClear(input: ExternalApiAuthHeaderClearInput!): ExternalApiAuthHeaderClearPayload! @auth(only: USER)
@@ -54,7 +60,9 @@ externalApiAuthHeaderClear(input: ExternalApiAuthHeaderClearInput!): ExternalApi
 
 ### `externalApiOAuth2Set`
 
-Set or replace the OAuth2 credential on an external API, removing a static auth header it holds. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected.
+Sets the OAuth2 credential of an external API, and removes any static auth header. The next call
+fetches a new access token.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 externalApiOAuth2Set(input: ExternalApiOAuth2SetInput!): ExternalApiOAuth2SetPayload! @auth(only: USER)
@@ -62,7 +70,9 @@ externalApiOAuth2Set(input: ExternalApiOAuth2SetInput!): ExternalApiOAuth2SetPay
 
 ### `externalApiOAuth2Clear`
 
-Remove the OAuth2 credential, its secrets and its cached access token from an external API. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected.
+Removes the OAuth2 credential of an external API, with its secrets and cached access token. An
+external API with no OAuth2 credential is unchanged.
+Scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
 
 ```graphql
 externalApiOAuth2Clear(input: ExternalApiOAuth2ClearInput!): ExternalApiOAuth2ClearPayload! @auth(only: USER)
@@ -70,7 +80,8 @@ externalApiOAuth2Clear(input: ExternalApiOAuth2ClearInput!): ExternalApiOAuth2Cl
 
 ### `externalApiDelete`
 
-Delete an external API registration and its encrypted credentials. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_DELETE`; API keys are rejected.
+Deletes an external API and its credential. Workflows then cannot call its origin.
+Scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
 
 ```graphql
 externalApiDelete(input: ExternalApiDeleteInput!): ExternalApiDeletePayload! @auth(only: USER)
@@ -83,12 +94,12 @@ externalApiDelete(input: ExternalApiDeleteInput!): ExternalApiDeletePayload! @au
 ```graphql
 """How an external API authenticates the requests a workflow sends it."""
 enum ExternalApiAuthKind {
-  """No credential: requests carry no auth header from the registry."""
+  """No credential."""
   NONE
   """A static auth header, set with `externalApiAuthHeaderSet`."""
   HEADER
   """
-  An OAuth2 credential, set with `externalApiOAuth2Set`. The registry fetches an access token, caches it and refreshes it.
+  An OAuth2 credential, set with `externalApiOAuth2Set`. Picked fetches, caches and refreshes the access token.
   """
   OAUTH2
 }
@@ -97,16 +108,14 @@ enum ExternalApiAuthKind {
 ### `ExternalApiOAuth2Grant`
 
 ```graphql
-"""
-The OAuth2 grant an external API's credential fetches its access token with.
-"""
+"""The OAuth2 grant that fetches the access token of an external API."""
 enum ExternalApiOAuth2Grant {
   """
-  The refresh-token grant (RFC 6749 section 6): the token request carries a stored refresh token.
+  The refresh-token grant (RFC 6749 section 6), which sends a stored refresh token.
   """
   REFRESH_TOKEN
   """
-  The client-credentials grant (RFC 6749 section 4.4): the token request carries the client alone.
+  The client-credentials grant (RFC 6749 section 4.4), which sends the client alone.
   """
   CLIENT_CREDENTIALS
 }
@@ -115,7 +124,7 @@ enum ExternalApiOAuth2Grant {
 ### `ExternalApiOAuth2ClientAuth`
 
 ```graphql
-"""Where the token request carries the client id and the client secret."""
+"""Where the token request carries the client ID and the client secret."""
 enum ExternalApiOAuth2ClientAuth {
   """As `client_id` and `client_secret` parameters in the form body."""
   BODY
@@ -128,20 +137,20 @@ enum ExternalApiOAuth2ClientAuth {
 
 ```graphql
 """
-Why the registry could not supply an access token. A failed `http` node
-records the same reason, in lower case, as `error.reason`.
+Why Picked could not get an access token. A failed `http` node records the same reason, in lower
+case, as `error.reason`.
 """
 enum ExternalApiCredentialFailureReason {
   """
-  The token endpoint refused the credential (`invalid_client`, `invalid_grant`, `invalid_code`, `invalid_client_secret` or `unauthorized_client`). Not retryable: the credential needs fixing.
+  The token endpoint refused the credential, such as with `invalid_client` or `invalid_grant`. Not retryable: the credential needs fixing.
   """
   CREDENTIAL_REJECTED
   """
-  The token endpoint timed out, could not be reached, answered 429 or 5xx, or answered without a token for another reason; or the node's timeout ran out first. Retryable. Callers fail at once for 60 seconds after one.
+  The token endpoint timed out, could not be reached, answered 429 or 5xx, or sent no token, or the node timed out first. Retryable; calls fail at once for 60 seconds after.
   """
   CREDENTIAL_REFRESH_FAILED
   """
-  The vault no longer holds a secret the credential names. Not retryable: set the credential again.
+  A secret of the credential is missing. Not retryable: set the credential again.
   """
   CREDENTIAL_UNAVAILABLE
 }
@@ -150,11 +159,11 @@ enum ExternalApiCredentialFailureReason {
 ### `ExternalApiOAuth2TokenParam`
 
 ```graphql
-"""One extra parameter of the token request, such as `scope`."""
+"""An extra parameter of the token request, such as `scope`."""
 type ExternalApiOAuth2TokenParam {
-  """Parameter name."""
+  """The name of the parameter."""
   name: String!
-  """Parameter value."""
+  """The value of the parameter."""
   value: String!
 }
 ```
@@ -163,8 +172,8 @@ type ExternalApiOAuth2TokenParam {
 
 ```graphql
 """
-Which 401 answers mark the access token as expired. A 401 refreshes the token
-only when the JSON body's value at `path` is one of `values`.
+The 401 responses that mark the access token as expired: those whose JSON body holds one of
+`values` at `path`.
 """
 type ExternalApiOAuth2RefreshOn401 {
   """
@@ -181,11 +190,11 @@ type ExternalApiOAuth2RefreshOn401 {
 ### `ExternalApiOAuth2RefreshFailure`
 
 ```graphql
-"""The last token refresh that failed."""
+"""The last failed refresh of an access token."""
 type ExternalApiOAuth2RefreshFailure {
-  """Why it failed."""
+  """Why the refresh failed."""
   reason: ExternalApiCredentialFailureReason!
-  """When it failed."""
+  """When the refresh failed."""
   failedAt: DateTime!
 }
 ```
@@ -194,54 +203,43 @@ type ExternalApiOAuth2RefreshFailure {
 
 ```graphql
 """
-An external API's OAuth2 credential: the settings the registry fetches an
-access token with, and how its last refreshes went.
-
-The registry sends `<headerScheme> <access token>` in `headerName`. It uses a
-cached token until 60 seconds before it expires, and otherwise posts a
-form-encoded token request to `tokenUrl`, one refresh at a time per
-credential. A 401 to a token minted over a minute earlier, when
-`refreshOn401` is null or matches the body, discards the token and sends the
-request once more with a new one.
-
-The client secret and the refresh token are write-only: `clientSecretSet` and
-`refreshTokenSet` say whether each is held. No field returns an access token.
+The OAuth2 credential of an external API. Picked sends `<headerScheme> <access token>` in
+`headerName`, refreshes the token from `tokenUrl` 60 seconds before it expires, and retries once
+with a new token after a 401 that `refreshOn401` matches.
 """
 type ExternalApiOAuth2 {
   """The grant the token request uses."""
   grant: ExternalApiOAuth2Grant!
   """The token endpoint, an `https` URL."""
   tokenUrl: String!
-  """The OAuth2 client id."""
+  """The OAuth2 client ID."""
   clientId: String!
-  """
-  True when a client secret is held. The secret itself is never returned.
-  """
+  """Whether a client secret is set. The secret is never returned."""
   clientSecretSet: Boolean!
   """
-  True when a refresh token is held. Always false for `CLIENT_CREDENTIALS`. The token itself is never returned.
+  Whether a refresh token is set. Always false for `CLIENT_CREDENTIALS`. The token is never returned.
   """
   refreshTokenSet: Boolean!
   """Where the token request carries the client."""
   clientAuth: ExternalApiOAuth2ClientAuth!
-  """Extra token-request parameters, such as `scope`."""
+  """The extra parameters of the token request, such as `scope`."""
   tokenParams: [ExternalApiOAuth2TokenParam!]!
-  """The header the access token goes in, such as `Authorization`."""
+  """The header that carries the access token, such as `Authorization`."""
   headerName: String!
   """
-  The scheme before the access token in that header, such as `Bearer` or `Zoho-oauthtoken`.
+  The scheme before the access token in the header, such as `Bearer` or `Zoho-oauthtoken`.
   """
   headerScheme: String!
   """
-  Which 401 answers mark the token as expired, or null when every 401 does.
+  The 401 responses that mark the token as expired. Null when every 401 does.
   """
   refreshOn401: ExternalApiOAuth2RefreshOn401
   """
-  When the registry last stored a new access token, or null before the first refresh.
+  When Picked last stored a new access token. Null before the first refresh.
   """
   lastRefreshedAt: DateTime
   """
-  The last refresh that failed, or null when the last refresh succeeded or none has run.
+  The last failed refresh. Null when the last refresh succeeded or none has run.
   """
   lastRefreshFailure: ExternalApiOAuth2RefreshFailure
 }
@@ -251,44 +249,36 @@ type ExternalApiOAuth2 {
 
 ```graphql
 """
-An external API a project's workflows may call. A registration is one
-origin — scheme, host and optional port, no path — so `https://api.vendor.test`
-admits every path on that host. The `http` workflow tool sends a request only
-when the URL it resolves has a registered origin in the run's project, and
-attaches this API's credential when one is set.
-
-`authKind` says which credential the API holds: none, a static auth header,
-or an OAuth2 credential. Every secret is write-only: it is encrypted at rest
-and no field of this API returns it. `authHeaderSet` says whether a static
-header exists and `authHeaderName` which header it goes in; `oauth2` describes
-an OAuth2 credential.
+An origin that the workflows of a project can call with the `http` tool, and the credential that
+Picked attaches to those calls. Secrets are encrypted at rest and never returned.
 """
 type ExternalApi {
-  """Unique external API identifier (`xapi_…`)."""
+  """The ID of the external API."""
   id: ID!
-  """ID of the project this external API belongs to."""
+  """The ID of the project the external API belongs to."""
   projectId: ID!
-  """Display name."""
+  """The name of the external API."""
   name: String!
   """
-  The origin — scheme, host and optional port, with no path (e.g. `https://api.vendor.test`). Normalised: lower-case host, default port dropped.
+  The origin: scheme, host and optional port, with no path, such as `https://api.vendor.test`. The
+  host is lower case and a default port is dropped. Every path on the origin is allowed.
   """
   origin: String!
-  """How this external API authenticates."""
+  """The kind of credential."""
   authKind: ExternalApiAuthKind!
   """
-  The static auth header's name, or null when the external API holds no static header.
+  The name of the static auth header. Null when there is no static header.
   """
   authHeaderName: String
   """
-  True when a static auth header value is held (`authKind: HEADER`). The value itself is never returned.
+  Whether a static auth header value is set. The value is never returned.
   """
   authHeaderSet: Boolean!
-  """The OAuth2 credential, or null unless `authKind` is `OAUTH2`."""
+  """The OAuth2 credential. Null unless `authKind` is `OAUTH2`."""
   oauth2: ExternalApiOAuth2
-  """When this external API was registered."""
+  """When the external API was created."""
   createdAt: DateTime!
-  """When this external API was last updated."""
+  """When the external API last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -296,9 +286,9 @@ type ExternalApi {
 ### `ExternalApiEdge`
 
 ```graphql
-"""Edge type for the external API connection."""
+"""An external API in a page of results."""
 type ExternalApiEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The external API."""
   node: ExternalApi!
@@ -308,15 +298,13 @@ type ExternalApiEdge {
 ### `ExternalApiConnection`
 
 ```graphql
-"""
-Connection type for external APIs (Relay-style pagination), newest first.
-"""
+"""A page of external APIs, newest first."""
 type ExternalApiConnection {
-  """List of external API edges."""
+  """The edges in this page."""
   edges: [ExternalApiEdge!]!
-  """Pagination information."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of live external APIs registered to the project."""
+  """The total number of external APIs in the project."""
   totalCount: Int!
 }
 ```
@@ -324,13 +312,11 @@ type ExternalApiConnection {
 ### `ExternalApiAuthHeaderInput`
 
 ```graphql
-"""
-A single auth header to send when calling a registered external API. The value is encrypted at rest and only ever decrypted server-side, inside the workflow step that sends the request.
-"""
+"""A static auth header for the calls to an external API."""
 input ExternalApiAuthHeaderInput {
-  """Header name; defaults server-side to `authorization` when omitted."""
+  """The name of the header. Defaults to `authorization`."""
   name: String
-  """Header value to encrypt and persist."""
+  """The value of the header. Encrypted at rest and never returned."""
   value: String!
 }
 ```
@@ -338,11 +324,11 @@ input ExternalApiAuthHeaderInput {
 ### `ExternalApiOAuth2TokenParamInput`
 
 ```graphql
-"""One extra parameter of the token request."""
+"""An extra parameter of the token request."""
 input ExternalApiOAuth2TokenParamInput {
-  """Parameter name."""
+  """The name of the parameter."""
   name: String!
-  """Parameter value."""
+  """The value of the parameter."""
   value: String!
 }
 ```
@@ -350,7 +336,7 @@ input ExternalApiOAuth2TokenParamInput {
 ### `ExternalApiOAuth2RefreshOn401Input`
 
 ```graphql
-"""Which 401 answers mark the access token as expired."""
+"""The 401 responses that mark the access token as expired."""
 input ExternalApiOAuth2RefreshOn401Input {
   """
   A dot-separated path into the response body, such as `code`. A segment of digits indexes an array.
@@ -367,38 +353,42 @@ input ExternalApiOAuth2RefreshOn401Input {
 
 ```graphql
 """
-An OAuth2 credential to set when registering an external API. The client
-secret and the refresh token are encrypted at rest and only ever decrypted
-server-side, to request an access token.
+An OAuth2 credential to set when creating an external API. Secrets are encrypted at rest and
+never returned.
 """
 input ExternalApiOAuth2Input {
   """The grant the token request uses."""
   grant: ExternalApiOAuth2Grant!
   """
-  The token endpoint: an `https` URL that passes the same outbound checks as a node's request (public address, port 443 or 80), with no fragment and no `grant_type`, `client_id`, `client_secret`, `refresh_token` or `code` in its query. Setting it does not register its origin.
+  The token endpoint: a public `https` URL on port 443 or 80, with no fragment and no `grant_type`,
+  `client_id`, `client_secret`, `refresh_token` or `code` in its query. Its origin is not
+  registered.
   """
   tokenUrl: String!
-  """The OAuth2 client id."""
+  """The OAuth2 client ID."""
   clientId: String!
-  """The client secret, encrypted at rest and never returned. Required."""
+  """The client secret. Required."""
   clientSecret: String
   """
-  The refresh token, encrypted at rest and never returned. `REFRESH_TOKEN` requires one; `CLIENT_CREDENTIALS` refuses one.
+  The refresh token. Required for `REFRESH_TOKEN`; refused for `CLIENT_CREDENTIALS`.
   """
   refreshToken: String
   """Where the token request carries the client. Defaults to `BODY`."""
   clientAuth: ExternalApiOAuth2ClientAuth
   """
-  Extra token-request parameters, such as `scope`. `grant_type`, `client_id`, `client_secret`, `refresh_token` and `code` are refused: the credential sets those itself.
+  The extra parameters of the token request, such as `scope`. `grant_type`, `client_id`,
+  `client_secret`, `refresh_token` and `code` are refused.
   """
   tokenParams: [ExternalApiOAuth2TokenParamInput!]
-  """The header the access token goes in. Defaults to `Authorization`."""
+  """The header that carries the access token. Defaults to `Authorization`."""
   headerName: String
   """
   The scheme before the access token, an HTTP token with no spaces. Defaults to `Bearer`.
   """
   headerScheme: String
-  """Which 401 answers mark the token as expired. Omit it for every 401."""
+  """
+  The 401 responses that mark the token as expired. Omit to match every 401.
+  """
   refreshOn401: ExternalApiOAuth2RefreshOn401Input
 }
 ```
@@ -406,9 +396,9 @@ input ExternalApiOAuth2Input {
 ### `ExternalApiInput`
 
 ```graphql
-"""Input for the top-level `externalApi` query."""
+"""The input of `externalApi`."""
 input ExternalApiInput {
-  """ID of the external API to fetch."""
+  """The ID of the external API."""
   id: ID!
 }
 ```
@@ -416,23 +406,21 @@ input ExternalApiInput {
 ### `ExternalApiCreateInput`
 
 ```graphql
-"""Input for `externalApiCreate`."""
+"""The input of `externalApiCreate`."""
 input ExternalApiCreateInput {
-  """
-  Project the external API is registered to. The organisation is derived server-side from the project.
-  """
+  """The ID of the project."""
   projectId: ID!
-  """Display name."""
+  """The name of the external API."""
   name: String!
   """
-  The origin to allow: scheme, host and optional port, with no path, query, fragment or credentials. Validated server-side: must be http or https on port 80 or 443, and must not resolve to a private, loopback, link-local or reserved address.
+  The origin to allow: `http` or `https`, a host and an optional port 80 or 443, with no path,
+  query, fragment or credentials. The host must not resolve to a private, loopback, link-local or
+  reserved address.
   """
   origin: String!
-  """Optional auth header to set on registration. Refused beside `oauth2`."""
+  """A static auth header. Not allowed with `oauth2`."""
   authHeader: ExternalApiAuthHeaderInput
-  """
-  Optional OAuth2 credential to set on registration. Refused beside `authHeader`. A client secret is required, and a refresh token for `REFRESH_TOKEN`.
-  """
+  """An OAuth2 credential. Not allowed with `authHeader`."""
   oauth2: ExternalApiOAuth2Input
 }
 ```
@@ -440,13 +428,11 @@ input ExternalApiCreateInput {
 ### `ExternalApiUpdateInput`
 
 ```graphql
-"""
-Input for `externalApiUpdate`. Name-only: the origin is the registration's identity — to change it, delete and register again. The credential is managed by `externalApiAuthHeaderSet` / `externalApiAuthHeaderClear` and `externalApiOAuth2Set` / `externalApiOAuth2Clear`.
-"""
+"""The input of `externalApiUpdate`. Every field is required."""
 input ExternalApiUpdateInput {
-  """ID of the external API to update."""
+  """The ID of the external API."""
   id: ID!
-  """New display name."""
+  """The name of the external API."""
   name: String!
 }
 ```
@@ -454,15 +440,13 @@ input ExternalApiUpdateInput {
 ### `ExternalApiAuthHeaderSetInput`
 
 ```graphql
-"""
-Input for `externalApiAuthHeaderSet`. Creates or replaces the static auth header value, and removes an OAuth2 credential the external API holds.
-"""
+"""The input of `externalApiAuthHeaderSet`."""
 input ExternalApiAuthHeaderSetInput {
-  """ID of the external API."""
+  """The ID of the external API."""
   id: ID!
-  """Header name; defaults server-side to `authorization` when omitted."""
+  """The name of the header. Defaults to `authorization`."""
   name: String
-  """Header value to encrypt and persist."""
+  """The value of the header. Encrypted at rest and never returned."""
   value: String!
 }
 ```
@@ -470,11 +454,9 @@ input ExternalApiAuthHeaderSetInput {
 ### `ExternalApiAuthHeaderClearInput`
 
 ```graphql
-"""
-Input for `externalApiAuthHeaderClear`. Idempotent: clearing an external API that has no static header, an OAuth2 one included, is a no-op success.
-"""
+"""The input of `externalApiAuthHeaderClear`."""
 input ExternalApiAuthHeaderClearInput {
-  """ID of the external API."""
+  """The ID of the external API."""
   id: ID!
 }
 ```
@@ -483,45 +465,48 @@ input ExternalApiAuthHeaderClearInput {
 
 ```graphql
 """
-Input for `externalApiOAuth2Set`. Creates or replaces the external API's OAuth2
-credential, and removes a static auth header it holds. Replacing a credential
-discards its cached access token, so the next request refreshes. A secret
-omitted here keeps the one held while `tokenUrl`, `clientId` and `clientAuth`
-stay as they are; a change to any of them needs the client secret, and for
-`REFRESH_TOKEN` the refresh token, again.
+The input of `externalApiOAuth2Set`. An omitted secret keeps the one set, unless `tokenUrl`,
+`clientId` or `clientAuth` changes.
 """
 input ExternalApiOAuth2SetInput {
-  """ID of the external API."""
+  """The ID of the external API."""
   id: ID!
   """The grant the token request uses."""
   grant: ExternalApiOAuth2Grant!
   """
-  The token endpoint: an `https` URL that passes the same outbound checks as a node's request (public address, port 443 or 80), with no fragment and no `grant_type`, `client_id`, `client_secret`, `refresh_token` or `code` in its query. Setting it does not register its origin.
+  The token endpoint: a public `https` URL on port 443 or 80, with no fragment and no `grant_type`,
+  `client_id`, `client_secret`, `refresh_token` or `code` in its query. Its origin is not
+  registered.
   """
   tokenUrl: String!
-  """The OAuth2 client id."""
+  """The OAuth2 client ID."""
   clientId: String!
   """
-  The client secret, encrypted at rest and never returned. Required when no client secret is held, or when `tokenUrl`, `clientId` or `clientAuth` changes; omit it otherwise to keep the one held.
+  The client secret. Required when none is set, or when `tokenUrl`, `clientId` or `clientAuth`
+  changes.
   """
   clientSecret: String
   """
-  The refresh token, encrypted at rest and never returned. `REFRESH_TOKEN` requires one when none is held, or when `tokenUrl`, `clientId` or `clientAuth` changes, and omitting it otherwise keeps the one held; `CLIENT_CREDENTIALS` refuses one.
+  The refresh token. For `REFRESH_TOKEN`, required when none is set, or when `tokenUrl`, `clientId`
+  or `clientAuth` changes. Refused for `CLIENT_CREDENTIALS`.
   """
   refreshToken: String
   """Where the token request carries the client. Defaults to `BODY`."""
   clientAuth: ExternalApiOAuth2ClientAuth
   """
-  Extra token-request parameters, such as `scope`. `grant_type`, `client_id`, `client_secret`, `refresh_token` and `code` are refused: the credential sets those itself.
+  The extra parameters of the token request, such as `scope`. `grant_type`, `client_id`,
+  `client_secret`, `refresh_token` and `code` are refused.
   """
   tokenParams: [ExternalApiOAuth2TokenParamInput!]
-  """The header the access token goes in. Defaults to `Authorization`."""
+  """The header that carries the access token. Defaults to `Authorization`."""
   headerName: String
   """
   The scheme before the access token, an HTTP token with no spaces. Defaults to `Bearer`.
   """
   headerScheme: String
-  """Which 401 answers mark the token as expired. Omit it for every 401."""
+  """
+  The 401 responses that mark the token as expired. Omit to match every 401.
+  """
   refreshOn401: ExternalApiOAuth2RefreshOn401Input
 }
 ```
@@ -529,11 +514,9 @@ input ExternalApiOAuth2SetInput {
 ### `ExternalApiOAuth2ClearInput`
 
 ```graphql
-"""
-Input for `externalApiOAuth2Clear`. Idempotent: clearing an external API that holds no OAuth2 credential is a no-op success.
-"""
+"""The input of `externalApiOAuth2Clear`."""
 input ExternalApiOAuth2ClearInput {
-  """ID of the external API."""
+  """The ID of the external API."""
   id: ID!
 }
 ```
@@ -541,9 +524,9 @@ input ExternalApiOAuth2ClearInput {
 ### `ExternalApiDeleteInput`
 
 ```graphql
-"""Input for `externalApiDelete`."""
+"""The input of `externalApiDelete`."""
 input ExternalApiDeleteInput {
-  """ID of the external API to delete."""
+  """The ID of the external API."""
   id: ID!
 }
 ```
@@ -551,12 +534,13 @@ input ExternalApiDeleteInput {
 ### `ExternalApiCreatePayload`
 
 ```graphql
-"""Payload for `externalApiCreate`."""
+"""The result of `externalApiCreate`."""
 type ExternalApiCreatePayload {
-  """The registered external API, or null when `errors` is non-empty."""
+  """The external API. Null when `errors` is not empty."""
   externalApi: ExternalApi
   """
-  Validation errors. `ORIGIN_ALREADY_REGISTERED` on `origin` when a live registration for that origin exists in the project. An empty array indicates success.
+  The errors: `ORIGIN_ALREADY_REGISTERED` on `origin` when the project already has the origin. Empty
+  on success.
   """
   errors: [UserError!]!
 }
@@ -565,11 +549,11 @@ type ExternalApiCreatePayload {
 ### `ExternalApiUpdatePayload`
 
 ```graphql
-"""Payload for `externalApiUpdate`."""
+"""The result of `externalApiUpdate`."""
 type ExternalApiUpdatePayload {
-  """The updated external API, or null when `errors` is non-empty."""
+  """The external API."""
   externalApi: ExternalApi
-  """Validation errors. An empty array indicates success."""
+  """The errors. Always empty."""
   errors: [UserError!]!
 }
 ```
@@ -577,11 +561,11 @@ type ExternalApiUpdatePayload {
 ### `ExternalApiAuthHeaderSetPayload`
 
 ```graphql
-"""Payload for `externalApiAuthHeaderSet`."""
+"""The result of `externalApiAuthHeaderSet`."""
 type ExternalApiAuthHeaderSetPayload {
-  """The updated external API, or null when `errors` is non-empty."""
+  """The external API."""
   externalApi: ExternalApi
-  """Validation errors. An empty array indicates success."""
+  """The errors. Always empty."""
   errors: [UserError!]!
 }
 ```
@@ -589,11 +573,11 @@ type ExternalApiAuthHeaderSetPayload {
 ### `ExternalApiAuthHeaderClearPayload`
 
 ```graphql
-"""Payload for `externalApiAuthHeaderClear`."""
+"""The result of `externalApiAuthHeaderClear`."""
 type ExternalApiAuthHeaderClearPayload {
-  """The updated external API, or null when `errors` is non-empty."""
+  """The external API."""
   externalApi: ExternalApi
-  """Validation errors. An empty array indicates success."""
+  """The errors. Always empty."""
   errors: [UserError!]!
 }
 ```
@@ -601,11 +585,11 @@ type ExternalApiAuthHeaderClearPayload {
 ### `ExternalApiOAuth2SetPayload`
 
 ```graphql
-"""Payload for `externalApiOAuth2Set`."""
+"""The result of `externalApiOAuth2Set`."""
 type ExternalApiOAuth2SetPayload {
-  """The updated external API, or null when `errors` is non-empty."""
+  """The external API."""
   externalApi: ExternalApi
-  """Validation errors. An empty array indicates success."""
+  """The errors. Always empty."""
   errors: [UserError!]!
 }
 ```
@@ -613,11 +597,11 @@ type ExternalApiOAuth2SetPayload {
 ### `ExternalApiOAuth2ClearPayload`
 
 ```graphql
-"""Payload for `externalApiOAuth2Clear`."""
+"""The result of `externalApiOAuth2Clear`."""
 type ExternalApiOAuth2ClearPayload {
-  """The updated external API, or null when `errors` is non-empty."""
+  """The external API."""
   externalApi: ExternalApi
-  """Validation errors. An empty array indicates success."""
+  """The errors. Always empty."""
   errors: [UserError!]!
 }
 ```
@@ -625,13 +609,11 @@ type ExternalApiOAuth2ClearPayload {
 ### `ExternalApiDeletePayload`
 
 ```graphql
-"""Payload for `externalApiDelete`."""
+"""The result of `externalApiDelete`."""
 type ExternalApiDeletePayload {
-  """
-  True when the external API was deleted. Deleting one that is already gone is a no-op success.
-  """
+  """Whether the external API was deleted."""
   success: Boolean!
-  """Validation errors. An empty array indicates success."""
+  """The errors. Always empty."""
   errors: [UserError!]!
 }
 ```