picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,637 @@
+---
+type: reference
+layout: docs
+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.
+
+## 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.
+
+```graphql
+externalApi(input: ExternalApiInput!): ExternalApi @auth
+```
+
+## Mutations
+
+### `externalApiCreate`
+
+Register an external API to a project. Requires a user context and `ORGANIZATION_INTEGRATIONS_CREATE`; API keys are rejected.
+
+```graphql
+externalApiCreate(input: ExternalApiCreateInput!): ExternalApiCreatePayload! @auth(only: USER)
+```
+
+### `externalApiUpdate`
+
+Rename an external API. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected.
+
+```graphql
+externalApiUpdate(input: ExternalApiUpdateInput!): ExternalApiUpdatePayload! @auth(only: USER)
+```
+
+### `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.
+
+```graphql
+externalApiAuthHeaderSet(input: ExternalApiAuthHeaderSetInput!): ExternalApiAuthHeaderSetPayload! @auth(only: USER)
+```
+
+### `externalApiAuthHeaderClear`
+
+Remove the static auth header from an external API. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected.
+
+```graphql
+externalApiAuthHeaderClear(input: ExternalApiAuthHeaderClearInput!): ExternalApiAuthHeaderClearPayload! @auth(only: USER)
+```
+
+### `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.
+
+```graphql
+externalApiOAuth2Set(input: ExternalApiOAuth2SetInput!): ExternalApiOAuth2SetPayload! @auth(only: USER)
+```
+
+### `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.
+
+```graphql
+externalApiOAuth2Clear(input: ExternalApiOAuth2ClearInput!): ExternalApiOAuth2ClearPayload! @auth(only: USER)
+```
+
+### `externalApiDelete`
+
+Delete an external API registration and its encrypted credentials. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_DELETE`; API keys are rejected.
+
+```graphql
+externalApiDelete(input: ExternalApiDeleteInput!): ExternalApiDeletePayload! @auth(only: USER)
+```
+
+## Types
+
+### `ExternalApiAuthKind`
+
+```graphql
+"""How an external API authenticates the requests a workflow sends it."""
+enum ExternalApiAuthKind {
+  """No credential: requests carry no auth header from the registry."""
+  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.
+  """
+  OAUTH2
+}
+```
+
+### `ExternalApiOAuth2Grant`
+
+```graphql
+"""
+The OAuth2 grant an external API's credential fetches its access token with.
+"""
+enum ExternalApiOAuth2Grant {
+  """
+  The refresh-token grant (RFC 6749 section 6): the token request carries a stored refresh token.
+  """
+  REFRESH_TOKEN
+  """
+  The client-credentials grant (RFC 6749 section 4.4): the token request carries the client alone.
+  """
+  CLIENT_CREDENTIALS
+}
+```
+
+### `ExternalApiOAuth2ClientAuth`
+
+```graphql
+"""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
+  """In an `Authorization: Basic` header."""
+  BASIC
+}
+```
+
+### `ExternalApiCredentialFailureReason`
+
+```graphql
+"""
+Why the registry could not supply 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.
+  """
+  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.
+  """
+  CREDENTIAL_REFRESH_FAILED
+  """
+  The vault no longer holds a secret the credential names. Not retryable: set the credential again.
+  """
+  CREDENTIAL_UNAVAILABLE
+}
+```
+
+### `ExternalApiOAuth2TokenParam`
+
+```graphql
+"""One extra parameter of the token request, such as `scope`."""
+type ExternalApiOAuth2TokenParam {
+  """Parameter name."""
+  name: String!
+  """Parameter value."""
+  value: String!
+}
+```
+
+### `ExternalApiOAuth2RefreshOn401`
+
+```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`.
+"""
+type ExternalApiOAuth2RefreshOn401 {
+  """
+  A dot-separated path into the response body, such as `code`. A segment of digits indexes an array.
+  """
+  path: String!
+  """
+  The values at `path` that mark the token as expired, such as `INVALID_TOKEN`.
+  """
+  values: [String!]!
+}
+```
+
+### `ExternalApiOAuth2RefreshFailure`
+
+```graphql
+"""The last token refresh that failed."""
+type ExternalApiOAuth2RefreshFailure {
+  """Why it failed."""
+  reason: ExternalApiCredentialFailureReason!
+  """When it failed."""
+  failedAt: DateTime!
+}
+```
+
+### `ExternalApiOAuth2`
+
+```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.
+"""
+type ExternalApiOAuth2 {
+  """The grant the token request uses."""
+  grant: ExternalApiOAuth2Grant!
+  """The token endpoint, an `https` URL."""
+  tokenUrl: String!
+  """The OAuth2 client id."""
+  clientId: String!
+  """
+  True when a client secret is held. The secret itself is never returned.
+  """
+  clientSecretSet: Boolean!
+  """
+  True when a refresh token is held. Always false for `CLIENT_CREDENTIALS`. The token itself is never returned.
+  """
+  refreshTokenSet: Boolean!
+  """Where the token request carries the client."""
+  clientAuth: ExternalApiOAuth2ClientAuth!
+  """Extra token-request parameters, such as `scope`."""
+  tokenParams: [ExternalApiOAuth2TokenParam!]!
+  """The header the access token goes in, such as `Authorization`."""
+  headerName: String!
+  """
+  The scheme before the access token in that header, such as `Bearer` or `Zoho-oauthtoken`.
+  """
+  headerScheme: String!
+  """
+  Which 401 answers mark the token as expired, or null when every 401 does.
+  """
+  refreshOn401: ExternalApiOAuth2RefreshOn401
+  """
+  When the registry last stored a new access token, or null before the first refresh.
+  """
+  lastRefreshedAt: DateTime
+  """
+  The last refresh that failed, or null when the last refresh succeeded or none has run.
+  """
+  lastRefreshFailure: ExternalApiOAuth2RefreshFailure
+}
+```
+
+### `ExternalApi`
+
+```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.
+"""
+type ExternalApi {
+  """Unique external API identifier (`xapi_…`)."""
+  id: ID!
+  """ID of the project this external API belongs to."""
+  projectId: ID!
+  """Display name."""
+  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.
+  """
+  origin: String!
+  """How this external API authenticates."""
+  authKind: ExternalApiAuthKind!
+  """
+  The static auth header's name, or null when the external API holds no static header.
+  """
+  authHeaderName: String
+  """
+  True when a static auth header value is held (`authKind: HEADER`). The value itself is never returned.
+  """
+  authHeaderSet: Boolean!
+  """The OAuth2 credential, or null unless `authKind` is `OAUTH2`."""
+  oauth2: ExternalApiOAuth2
+  """When this external API was registered."""
+  createdAt: DateTime!
+  """When this external API was last updated."""
+  updatedAt: DateTime!
+}
+```
+
+### `ExternalApiEdge`
+
+```graphql
+"""Edge type for the external API connection."""
+type ExternalApiEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The external API."""
+  node: ExternalApi!
+}
+```
+
+### `ExternalApiConnection`
+
+```graphql
+"""
+Connection type for external APIs (Relay-style pagination), newest first.
+"""
+type ExternalApiConnection {
+  """List of external API edges."""
+  edges: [ExternalApiEdge!]!
+  """Pagination information."""
+  pageInfo: PageInfo!
+  """Total number of live external APIs registered to the project."""
+  totalCount: Int!
+}
+```
+
+### `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.
+"""
+input ExternalApiAuthHeaderInput {
+  """Header name; defaults server-side to `authorization` when omitted."""
+  name: String
+  """Header value to encrypt and persist."""
+  value: String!
+}
+```
+
+### `ExternalApiOAuth2TokenParamInput`
+
+```graphql
+"""One extra parameter of the token request."""
+input ExternalApiOAuth2TokenParamInput {
+  """Parameter name."""
+  name: String!
+  """Parameter value."""
+  value: String!
+}
+```
+
+### `ExternalApiOAuth2RefreshOn401Input`
+
+```graphql
+"""Which 401 answers 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.
+  """
+  path: String!
+  """
+  The values at `path` that mark the token as expired, such as `INVALID_TOKEN`. At least one.
+  """
+  values: [String!]!
+}
+```
+
+### `ExternalApiOAuth2Input`
+
+```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.
+"""
+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.
+  """
+  tokenUrl: String!
+  """The OAuth2 client id."""
+  clientId: String!
+  """The client secret, encrypted at rest and never returned. Required."""
+  clientSecret: String
+  """
+  The refresh token, encrypted at rest and never returned. `REFRESH_TOKEN` requires one; `CLIENT_CREDENTIALS` refuses one.
+  """
+  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.
+  """
+  tokenParams: [ExternalApiOAuth2TokenParamInput!]
+  """The header the access token goes in. 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."""
+  refreshOn401: ExternalApiOAuth2RefreshOn401Input
+}
+```
+
+### `ExternalApiInput`
+
+```graphql
+"""Input for the top-level `externalApi` query."""
+input ExternalApiInput {
+  """ID of the external API to fetch."""
+  id: ID!
+}
+```
+
+### `ExternalApiCreateInput`
+
+```graphql
+"""Input for `externalApiCreate`."""
+input ExternalApiCreateInput {
+  """
+  Project the external API is registered to. The organisation is derived server-side from the project.
+  """
+  projectId: ID!
+  """Display name."""
+  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.
+  """
+  origin: String!
+  """Optional auth header to set on registration. Refused beside `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`.
+  """
+  oauth2: ExternalApiOAuth2Input
+}
+```
+
+### `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`.
+"""
+input ExternalApiUpdateInput {
+  """ID of the external API to update."""
+  id: ID!
+  """New display name."""
+  name: String!
+}
+```
+
+### `ExternalApiAuthHeaderSetInput`
+
+```graphql
+"""
+Input for `externalApiAuthHeaderSet`. Creates or replaces the static auth header value, and removes an OAuth2 credential the external API holds.
+"""
+input ExternalApiAuthHeaderSetInput {
+  """ID of the external API."""
+  id: ID!
+  """Header name; defaults server-side to `authorization` when omitted."""
+  name: String
+  """Header value to encrypt and persist."""
+  value: String!
+}
+```
+
+### `ExternalApiAuthHeaderClearInput`
+
+```graphql
+"""
+Input for `externalApiAuthHeaderClear`. Idempotent: clearing an external API that has no static header, an OAuth2 one included, is a no-op success.
+"""
+input ExternalApiAuthHeaderClearInput {
+  """ID of the external API."""
+  id: ID!
+}
+```
+
+### `ExternalApiOAuth2SetInput`
+
+```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.
+"""
+input ExternalApiOAuth2SetInput {
+  """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.
+  """
+  tokenUrl: String!
+  """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.
+  """
+  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.
+  """
+  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.
+  """
+  tokenParams: [ExternalApiOAuth2TokenParamInput!]
+  """The header the access token goes in. 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."""
+  refreshOn401: ExternalApiOAuth2RefreshOn401Input
+}
+```
+
+### `ExternalApiOAuth2ClearInput`
+
+```graphql
+"""
+Input for `externalApiOAuth2Clear`. Idempotent: clearing an external API that holds no OAuth2 credential is a no-op success.
+"""
+input ExternalApiOAuth2ClearInput {
+  """ID of the external API."""
+  id: ID!
+}
+```
+
+### `ExternalApiDeleteInput`
+
+```graphql
+"""Input for `externalApiDelete`."""
+input ExternalApiDeleteInput {
+  """ID of the external API to delete."""
+  id: ID!
+}
+```
+
+### `ExternalApiCreatePayload`
+
+```graphql
+"""Payload for `externalApiCreate`."""
+type ExternalApiCreatePayload {
+  """The registered external API, or null when `errors` is non-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.
+  """
+  errors: [UserError!]!
+}
+```
+
+### `ExternalApiUpdatePayload`
+
+```graphql
+"""Payload for `externalApiUpdate`."""
+type ExternalApiUpdatePayload {
+  """The updated external API, or null when `errors` is non-empty."""
+  externalApi: ExternalApi
+  """Validation errors. An empty array indicates success."""
+  errors: [UserError!]!
+}
+```
+
+### `ExternalApiAuthHeaderSetPayload`
+
+```graphql
+"""Payload for `externalApiAuthHeaderSet`."""
+type ExternalApiAuthHeaderSetPayload {
+  """The updated external API, or null when `errors` is non-empty."""
+  externalApi: ExternalApi
+  """Validation errors. An empty array indicates success."""
+  errors: [UserError!]!
+}
+```
+
+### `ExternalApiAuthHeaderClearPayload`
+
+```graphql
+"""Payload for `externalApiAuthHeaderClear`."""
+type ExternalApiAuthHeaderClearPayload {
+  """The updated external API, or null when `errors` is non-empty."""
+  externalApi: ExternalApi
+  """Validation errors. An empty array indicates success."""
+  errors: [UserError!]!
+}
+```
+
+### `ExternalApiOAuth2SetPayload`
+
+```graphql
+"""Payload for `externalApiOAuth2Set`."""
+type ExternalApiOAuth2SetPayload {
+  """The updated external API, or null when `errors` is non-empty."""
+  externalApi: ExternalApi
+  """Validation errors. An empty array indicates success."""
+  errors: [UserError!]!
+}
+```
+
+### `ExternalApiOAuth2ClearPayload`
+
+```graphql
+"""Payload for `externalApiOAuth2Clear`."""
+type ExternalApiOAuth2ClearPayload {
+  """The updated external API, or null when `errors` is non-empty."""
+  externalApi: ExternalApi
+  """Validation errors. An empty array indicates success."""
+  errors: [UserError!]!
+}
+```
+
+### `ExternalApiDeletePayload`
+
+```graphql
+"""Payload for `externalApiDelete`."""
+type ExternalApiDeletePayload {
+  """
+  True when the external API was deleted. Deleting one that is already gone is a no-op success.
+  """
+  success: Boolean!
+  """Validation errors. An empty array indicates success."""
+  errors: [UserError!]!
+}
+```