picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,749 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Organization schema
+
+The operations and types that `organization.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `organization`
+
+Fetch a single organisation by ID or slug. Requires authentication.
+
+```graphql
+organization(input: OrganizationInput!): Organization @auth
+```
+
+### `organizations`
+
+List organisations the authenticated user belongs to. Requires authentication.
+
+```graphql
+organizations(first: Int, after: String, search: String, sortKey: OrganizationSortKeys = NAME, reverse: Boolean = false): OrganizationConnection! @auth
+```
+
+## Mutations
+
+### `organizationCreate`
+
+Create a new organisation. Requires scope: `ORGANIZATION_CREATE`.
+
+```graphql
+organizationCreate(input: OrganizationCreateInput!): OrganizationCreatePayload! @auth
+```
+
+### `organizationUpdate`
+
+Update an organisation. Requires scope: `ORGANIZATION_UPDATE`.
+
+```graphql
+organizationUpdate(input: OrganizationUpdateInput!): OrganizationUpdatePayload! @auth
+```
+
+### `organizationDelete`
+
+Delete an organisation. Requires scope: `ORGANIZATION_DELETE`.
+
+```graphql
+organizationDelete(input: OrganizationDeleteInput!): OrganizationDeletePayload! @auth
+```
+
+### `organizationMemberInvite`
+
+Invite a member to an organisation. Requires scope: `ORGANIZATION_INVITATIONS_CREATE`.
+
+```graphql
+organizationMemberInvite(input: OrganizationMemberInviteInput!): OrganizationMemberInvitePayload! @auth
+```
+
+### `organizationInvitationAccept`
+
+Accept an organisation invitation. Requires authentication.
+
+```graphql
+organizationInvitationAccept(input: OrganizationInvitationAcceptInput!): OrganizationInvitationAcceptPayload! @auth
+```
+
+### `organizationInvitationDecline`
+
+Decline an organisation invitation. Requires authentication.
+
+```graphql
+organizationInvitationDecline(input: OrganizationInvitationDeclineInput!): OrganizationInvitationDeclinePayload! @auth
+```
+
+### `organizationInvitationRevoke`
+
+Revoke an organisation invitation. Requires scope: `ORGANIZATION_INVITATIONS_DELETE`.
+
+```graphql
+organizationInvitationRevoke(input: OrganizationInvitationRevokeInput!): OrganizationInvitationRevokePayload! @auth
+```
+
+### `organizationMemberRemove`
+
+Remove a member from an organisation. Requires scope: `ORGANIZATION_MEMBERS_DELETE`.
+
+```graphql
+organizationMemberRemove(input: OrganizationMemberRemoveInput!): OrganizationMemberRemovePayload! @auth
+```
+
+### `organizationMemberScopesUpdate`
+
+Set the scopes a member holds in an organisation. Requires
+`ORGANIZATION_MEMBERS_MANAGE_SCOPES` reaching that organisation. The target
+must be a member. A caller may not grant a scope they do not themselves hold,
+and may not edit their own scopes.
+
+```graphql
+organizationMemberScopesUpdate(input: OrganizationMemberScopesUpdateInput!): OrganizationMemberScopesUpdatePayload! @auth
+```
+
+### `organizationClientManagerScopesUpdate`
+
+Set the scopes a client manager holds in one organisation. Requires
+`STAFF_INVITE_CLIENT_MANAGER` at root. The target must be a client manager,
+and a caller may not edit their own scopes. A client manager may add or
+remove only scopes their own client-manager grant in that organisation
+carries; a super admin may set any.
+
+```graphql
+organizationClientManagerScopesUpdate(input: OrganizationClientManagerScopesUpdateInput!): OrganizationClientManagerScopesUpdatePayload! @auth
+```
+
+## Types
+
+### `OrganizationSortKeys`
+
+```graphql
+"""
+Sort keys accepted by `organizations(...)` and `User.organizations(...)`.
+
+Pair with `reverse: true` to flip the order (e.g. `NAME` + `reverse: false`
+sorts A→Z; `CREATED_AT` + `reverse: true` sorts newest-first).
+"""
+enum OrganizationSortKeys {
+  """Sort by organisation `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """
+  Sort by `updatedAt`. Pair with `reverse: true` for most-recently-changed first.
+  """
+  UPDATED_AT
+}
+```
+
+### `InvitationType`
+
+```graphql
+"""
+Invitation type. Historically, organisations could issue 24-hour multi-
+use invitations; that capability has been retired. All invitations are
+now single-use with a 30-day expiry.
+
+WARNING: This enum is retained for backwards compatibility with the
+deprecated `invitationType` argument on `organizationMemberInvite` and
+the deprecated `OrganizationInvitation.invitationType` field. Do not
+branch on it in new code.
+"""
+enum InvitationType {
+  """Single-use invitation that expires on acceptance or after 30 days."""
+  ONE_TIME @deprecated(reason: "All invitations are now single-use with 30-day expiration")
+  """Deprecated. Previously allowed 24-hour multi-use invitations."""
+  TWENTY_FOUR_HOUR @deprecated(reason: "All invitations are now single-use with 30-day expiration")
+}
+```
+
+### `Organization`
+
+```graphql
+"""
+An organisation — the top-level tenancy boundary for projects, API keys,
+integrations, and members.
+
+Every project, API key, and integration belongs to exactly one
+organisation. The set of scopes the current viewer holds in this
+organisation is available on `viewerScopes`; use it to drive
+client-side UX (which buttons to show, which actions to gate).
+"""
+type Organization {
+  """Unique organisation identifier."""
+  id: ID!
+  """Display name of the organisation."""
+  name: String!
+  """
+  URL-friendly slug for the organisation. Used in dashboard URLs and as a stable handle for the organisation.
+  """
+  slug: String
+  """When this organisation was created."""
+  createdAt: DateTime!
+  """When this organisation was last updated."""
+  updatedAt: DateTime!
+  """
+  Whether every member must hold an `AAL2` session. A member of an organisation
+  with this on is held to the MFA policy on every request, whichever
+  organisation the request names.
+  """
+  requireMfa: Boolean!
+  """Members of this organisation."""
+  members(first: Int, after: String): OrganizationMemberConnection!
+  """Pending invitations for this organisation."""
+  invitations(first: Int, after: String): OrganizationInvitationConnection!
+  """
+  Projects within this organisation. Filter by name with `search`
+  (case-insensitive substring) and order with `sortKey` (default `NAME`) plus
+  `reverse`.
+  """
+  projects(first: Int, after: String, search: String, sortKey: ProjectSortKeys = NAME, reverse: Boolean = false): ProjectConnection!
+  """API keys for this organisation."""
+  apiKeys(first: Int, after: String): ApiKeyConnection!
+  """
+  Scopes available to the current viewer in this organisation. Drives client-side UX gating.
+  """
+  viewerScopes: [Scope!]!
+  """
+  Every client manager, with the scopes their client-manager grant carries in
+  this organisation. Empty unless the viewer holds `STAFF_READ` at root.
+  """
+  clientManagerAccess: [OrganizationClientManagerAccess!]!
+}
+```
+
+### `OrganizationMember`
+
+```graphql
+"""
+A user's membership in an organisation. Carries the user's identifying
+fields denormalised from `auth.users`, plus the role and `joinedAt`
+timestamp.
+
+Member-level operations (`organizationMemberScopesUpdate`,
+`organizationMemberRemove`) require the corresponding scope on the
+parent organisation.
+"""
+type OrganizationMember {
+  """Unique member identifier (the membership row id, not the user id)."""
+  id: ID!
+  """Email address of the member."""
+  userEmail: String
+  """First name of the member."""
+  userFirstName: String
+  """Last name of the member."""
+  userLastName: String
+  """When the member joined the organisation."""
+  joinedAt: DateTime!
+  """
+  Whether this member holds a verified MFA factor. Resolved for the whole page in one batched lookup.
+  """
+  mfaState: MfaState!
+  """
+  The scope grants this member holds in the organisation, one entry per
+  location. Empty unless the viewer holds `ORGANIZATION_MEMBERS_MANAGE_SCOPES`
+  reaching this organisation.
+  """
+  scopeGrants: [MemberScopeGrant!]!
+}
+```
+
+### `MemberScopeGrant`
+
+```graphql
+"""A set of scopes a member holds at one location within an organisation."""
+type MemberScopeGrant {
+  """The project the scopes apply to, or null for the organisation itself."""
+  projectId: ID
+  """The scopes held at that location."""
+  scopes: [Scope!]!
+}
+```
+
+### `OrganizationClientManagerAccess`
+
+```graphql
+"""
+A client manager and the scopes they hold in one organisation, on top of the
+root grant that reaches every organisation.
+"""
+type OrganizationClientManagerAccess {
+  """The client manager."""
+  user: AdminUser!
+  """
+  The scopes their client-manager grant carries on this organisation. Empty
+  when they hold none here.
+  """
+  scopes: [Scope!]!
+}
+```
+
+### `OrganizationMemberEdge`
+
+```graphql
+"""Edge type for `OrganizationMemberConnection`."""
+type OrganizationMemberEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The organisation member."""
+  node: OrganizationMember!
+}
+```
+
+### `OrganizationMemberConnection`
+
+```graphql
+"""Relay-style connection of organisation members."""
+type OrganizationMemberConnection {
+  """List of member edges."""
+  edges: [OrganizationMemberEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of members."""
+  totalCount: Int!
+}
+```
+
+### `OrganizationInvitation`
+
+```graphql
+"""
+An invitation to join an organisation. Created via
+`organizationMemberInvite`, accepted via `organizationInvitationAccept`,
+declined via `organizationInvitationDecline`, and revoked by the inviter
+via `organizationInvitationRevoke`.
+
+Invitations expire 30 days after creation (server-enforced; see
+`expiresAt`). Once accepted, the row remains for audit but cannot be
+re-accepted.
+"""
+type OrganizationInvitation {
+  """Unique invitation identifier."""
+  id: ID!
+  """
+  Invitation type — retained for backwards compatibility. All invitations are now single-use.
+  """
+  invitationType: InvitationType! @deprecated(reason: "All invitations are now single-use. This field will be removed.")
+  """When this invitation was created."""
+  createdAt: DateTime!
+  """When this invitation expires."""
+  expiresAt: DateTime!
+  """Email address of the invited user."""
+  userEmail: String
+}
+```
+
+### `OrganizationInvitationEdge`
+
+```graphql
+"""Edge type for `OrganizationInvitationConnection`."""
+type OrganizationInvitationEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The organisation invitation."""
+  node: OrganizationInvitation!
+}
+```
+
+### `OrganizationInvitationConnection`
+
+```graphql
+"""Relay-style connection of organisation invitations."""
+type OrganizationInvitationConnection {
+  """List of invitation edges."""
+  edges: [OrganizationInvitationEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of invitations."""
+  totalCount: Int!
+}
+```
+
+### `ViewerInvitation`
+
+```graphql
+"""
+An invitation addressed to the authenticated viewer, exposed via
+`User.invitations`. Carries the organisation name (so the dashboard can
+render a "Join <Org>" CTA without an extra fetch) plus the `token` the
+client passes to `organizationInvitationAccept` /
+`organizationInvitationDecline`.
+
+WARNING: `token` is sensitive — it grants the bearer the right to join
+the organisation. Treat it like a one-time secret.
+"""
+type ViewerInvitation {
+  """Unique invitation identifier."""
+  id: ID!
+  """Token used to accept or decline the invitation. Treat as sensitive."""
+  token: String!
+  """Name of the inviting organisation."""
+  organizationName: String!
+  """When this invitation was created."""
+  createdAt: DateTime!
+  """When this invitation expires."""
+  expiresAt: DateTime!
+}
+```
+
+### `ViewerInvitationEdge`
+
+```graphql
+"""Edge type for `ViewerInvitationConnection`."""
+type ViewerInvitationEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The viewer invitation."""
+  node: ViewerInvitation!
+}
+```
+
+### `ViewerInvitationConnection`
+
+```graphql
+"""Relay-style connection of the viewer's pending invitations."""
+type ViewerInvitationConnection {
+  """List of invitation edges."""
+  edges: [ViewerInvitationEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of invitations."""
+  totalCount: Int!
+}
+```
+
+### `OrganizationEdge`
+
+```graphql
+"""Edge type for `OrganizationConnection`."""
+type OrganizationEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The organisation."""
+  node: Organization!
+}
+```
+
+### `OrganizationConnection`
+
+```graphql
+"""Relay-style connection of organisations."""
+type OrganizationConnection {
+  """List of organisation edges."""
+  edges: [OrganizationEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of organisations."""
+  totalCount: Int!
+}
+```
+
+### `OrganizationInput`
+
+```graphql
+"""
+Input for looking up a single organisation. Provide either `id` or `slug` — at least one is required.
+"""
+input OrganizationInput {
+  """Organisation ID to look up."""
+  id: ID
+  """Organisation slug to look up."""
+  slug: String
+}
+```
+
+### `OrganizationCreateInput`
+
+```graphql
+"""Input for `organizationCreate`."""
+input OrganizationCreateInput {
+  """Name of the organisation."""
+  name: String!
+  """
+  URL-friendly slug for the organisation. Must be unique across all organisations.
+  """
+  slug: String!
+}
+```
+
+### `OrganizationCreatePayload`
+
+```graphql
+"""Payload returned by `organizationCreate`."""
+type OrganizationCreatePayload {
+  """The newly created organisation."""
+  organization: Organization
+}
+```
+
+### `OrganizationUpdateInput`
+
+```graphql
+"""Input for `organizationUpdate`."""
+input OrganizationUpdateInput {
+  """ID of the organisation to update."""
+  id: ID!
+  """New name for the organisation. Omit to keep the existing value."""
+  name: String
+  """New slug for the organisation. Must remain unique."""
+  slug: String
+  """
+  Whether every member must hold an `AAL2` session. Setting it to true needs
+  the caller's own session at `AAL2` (an `AAL1` or OAuth-client token is
+  refused with `MFA_REQUIRED`) and revokes every member's OAuth-client sessions.
+  """
+  requireMfa: Boolean
+}
+```
+
+### `OrganizationUpdatePayload`
+
+```graphql
+"""Payload returned by `organizationUpdate`."""
+type OrganizationUpdatePayload {
+  """The updated organisation."""
+  organization: Organization
+}
+```
+
+### `OrganizationDeleteInput`
+
+```graphql
+"""Input for `organizationDelete`."""
+input OrganizationDeleteInput {
+  """ID of the organisation to delete."""
+  id: ID!
+}
+```
+
+### `OrganizationDeletePayload`
+
+```graphql
+"""Payload returned by `organizationDelete`."""
+type OrganizationDeletePayload {
+  """ID of the deleted organisation."""
+  deletedOrganizationId: ID
+}
+```
+
+### `OrganizationMemberInviteInput`
+
+```graphql
+"""
+Input for `organizationMemberInvite` — create a pending invitation for the given email.
+"""
+input OrganizationMemberInviteInput {
+  """ID of the organisation to invite the member to."""
+  organizationId: ID!
+  """Email address of the user to invite."""
+  email: String!
+  """
+  Scopes the invitation grants on acceptance, one entry per location. Omit to
+  grant the preset matching `role`. The inviter may not grant a scope they do
+  not themselves hold.
+  """
+  grants: [MemberScopeGrantInput!]
+  """Invitation type. Ignored; retained for backwards compatibility."""
+  invitationType: InvitationType @deprecated(reason: "All invitations are now single-use. This field is ignored.")
+  """URL to redirect the invited user to after email verification."""
+  redirectUrl: String
+}
+```
+
+### `InvitationDelivery`
+
+```graphql
+"""Which email reached the person an invitation was sent to."""
+enum InvitationDelivery {
+  """An invitation email, for an address with no account."""
+  INVITE_EMAIL
+  """
+  A sign-in email, for an address that already has an account. The invitation
+  waits on the user's Account page.
+  """
+  SIGN_IN_EMAIL
+  """
+  No email went out. The invitation still waits on the Account page of a user with the address.
+  """
+  NOT_SENT
+}
+```
+
+### `OrganizationMemberInvitePayload`
+
+```graphql
+"""Payload returned by `organizationMemberInvite`."""
+type OrganizationMemberInvitePayload {
+  """The created invitation."""
+  invitation: OrganizationInvitation
+  """Which email reached the invitee."""
+  delivery: InvitationDelivery!
+}
+```
+
+### `OrganizationInvitationAcceptInput`
+
+```graphql
+"""Input for `organizationInvitationAccept`."""
+input OrganizationInvitationAcceptInput {
+  """Token from the invitation email — see `ViewerInvitation.token`."""
+  token: String!
+}
+```
+
+### `AcceptedMembership`
+
+```graphql
+"""Membership information returned after accepting an invitation."""
+type AcceptedMembership {
+  """ID of the organisation joined."""
+  organizationId: ID!
+  """Name of the organisation joined."""
+  organizationName: String!
+}
+```
+
+### `OrganizationInvitationAcceptPayload`
+
+```graphql
+"""Payload returned by `organizationInvitationAccept`."""
+type OrganizationInvitationAcceptPayload {
+  """The membership created by accepting the invitation."""
+  membership: AcceptedMembership
+}
+```
+
+### `OrganizationInvitationDeclineInput`
+
+```graphql
+"""Input for `organizationInvitationDecline`."""
+input OrganizationInvitationDeclineInput {
+  """Token from the invitation email."""
+  token: String!
+}
+```
+
+### `OrganizationInvitationDeclinePayload`
+
+```graphql
+"""Payload returned by `organizationInvitationDecline`."""
+type OrganizationInvitationDeclinePayload {
+  """Token of the declined invitation."""
+  declinedToken: String
+}
+```
+
+### `OrganizationInvitationRevokeInput`
+
+```graphql
+"""
+Input for `organizationInvitationRevoke` — withdraw a pending invitation.
+"""
+input OrganizationInvitationRevokeInput {
+  """ID of the invitation to revoke."""
+  invitationId: ID!
+  """ID of the organisation the invitation belongs to."""
+  organizationId: ID!
+}
+```
+
+### `OrganizationInvitationRevokePayload`
+
+```graphql
+"""Payload returned by `organizationInvitationRevoke`."""
+type OrganizationInvitationRevokePayload {
+  """ID of the revoked invitation."""
+  revokedInvitationId: ID
+}
+```
+
+### `OrganizationMemberRemoveInput`
+
+```graphql
+"""Input for `organizationMemberRemove`."""
+input OrganizationMemberRemoveInput {
+  """ID of the organisation to remove the member from."""
+  organizationId: ID!
+  """ID of the user to remove."""
+  userId: ID!
+}
+```
+
+### `OrganizationMemberRemovePayload`
+
+```graphql
+"""Payload returned by `organizationMemberRemove`."""
+type OrganizationMemberRemovePayload {
+  """ID of the removed user."""
+  removedUserId: ID
+}
+```
+
+### `MemberScopeGrantInput`
+
+```graphql
+"""A set of scopes to grant at one location within an organisation."""
+input MemberScopeGrantInput {
+  """The project the scopes apply to, or null for the organisation itself."""
+  projectId: ID
+  """The scopes to hold at that location."""
+  scopes: [Scope!]!
+}
+```
+
+### `OrganizationMemberScopesUpdateInput`
+
+```graphql
+"""Input for `organizationMemberScopesUpdate`."""
+input OrganizationMemberScopesUpdateInput {
+  """ID of the organisation."""
+  organizationId: ID!
+  """ID of the member whose scopes to set."""
+  userId: ID!
+  """
+  The grants to leave in place. Locations absent from this list are cleared;
+  grants outside this organisation are untouched.
+  """
+  grants: [MemberScopeGrantInput!]!
+}
+```
+
+### `OrganizationMemberScopesUpdatePayload`
+
+```graphql
+"""Payload returned by `organizationMemberScopesUpdate`."""
+type OrganizationMemberScopesUpdatePayload {
+  """The member whose scopes were set."""
+  member: OrganizationMember
+}
+```
+
+### `OrganizationClientManagerScopesUpdateInput`
+
+```graphql
+"""Input for `organizationClientManagerScopesUpdate`."""
+input OrganizationClientManagerScopesUpdateInput {
+  """ID of the organisation."""
+  organizationId: ID!
+  """ID of the client manager whose scopes to set."""
+  userId: ID!
+  """
+  The scopes to hold on this organisation, replacing whatever was held before.
+  An empty list clears the grant, leaving the root grant as their whole reach.
+  Root-located scopes are rejected: they bind to no organisation.
+  """
+  scopes: [Scope!]!
+}
+```
+
+### `OrganizationClientManagerScopesUpdatePayload`
+
+```graphql
+"""Payload returned by `organizationClientManagerScopesUpdate`."""
+type OrganizationClientManagerScopesUpdatePayload {
+  """The client manager whose scopes were set."""
+  access: OrganizationClientManagerAccess
+}
+```