Saltar al contenido principal

Referencia GraphQL: user-management-admin

Generada a partir del esquema que sirve este servicio, así que no puede quedarse atrás. El mismo esquema se publica como archivo para herramientas y agentes.

Endpointhttps://<your-host>/api/user-management/admin/graphql
Plano de autenticaciónidentity — Instance-scoped administration. Takes the identity token login returns BEFORE a tenant is selected, and is authorized for the superuser or an operator. A tenant access token is rejected here.
Autorizaciónidentity token
Archivo del esquema/schema/user-management-admin.graphql
Descritos555 de 555 elementos
nota

La referencia que sigue se genera a partir del esquema y está solo en inglés.

Queries​

auditEvents · authorities · deadLetter · deadLetters · functionalAreas · governanceDimensions · identities · idpConnection · idpConnections · oauthClients · ping · roles · ssoLinkRequests · tenantAgentActuation · tenantDeletion · tenantDeletions · tenantTiers · tenants · tierColorPalette

auditEvents​

Searches the audit journal of sign-ins, token refreshes and administrative changes, across all tenants, newest first. Requires audit:read.

Returns AdminAuditEventSearchResults!

ArgumentTypeDescription
criteriaAdminAuditEventSearchCriteria!Filters and paging for the search.

authorities​

The authorities that can be granted to a role, sorted, including *. With a scope, only the authorities a role of that scope may grant, since a role cannot be granted an authority that belongs to the other scope. Fails if scope is neither system nor tenant. Requires role:read.

Returns [String!]!

ArgumentTypeDescription
scopeStringsystem or tenant. Omit it to list every authority.

deadLetter​

One dead-letter record by its id. Returns null if there is none; fails if the id is not a number. Requires audit:read.

Returns DeadLetter

ArgumentTypeDescription
idID!Id of the record, as returned in the id field.

deadLetters​

Searches the work the platform accepted and gave up on, across all tenants, newest first. Requires audit:read.

Returns DeadLetterSearchResults!

ArgumentTypeDescription
criteriaDeadLetterSearchCriteria!Filters and paging for the search.

functionalAreas​

The names of the functional areas deployed on this instance, so a client can tell a feature that was never deployed from a server that is failing. It reports what the operator enabled, not whether each area is healthy. Requires only a valid identity token.

Returns [String!]!

governanceDimensions​

The governance dimensions the platform defines, so an editor can offer exactly the settings a tier or tenant may carry. The answer does not depend on the tenant. Requires tenant:read.

Returns [AdminGovernanceDimension!]!

identities​

Every identity on the instance, with its system roles and memberships. The list is not paged. Requires user:read.

Returns [AdminIdentity!]!

idpConnection​

Returns one identity provider connection, or null if there is none with that token. Requires user:read.

Returns IdpConnection

ArgumentTypeDescription
tokenString!Token of the connection.

idpConnections​

Lists the configured identity provider connections. Client secrets are never included. Requires user:read.

Returns [IdpConnection!]!

oauthClients​

The registered OAuth clients. Requires client:read.

Returns [AdminOAuthClient!]!

ping​

Liveness check. Always returns the string "pong".

Returns String!

roles​

The role catalog, optionally limited to one scope. Fails if scope is neither system nor tenant. Requires role:read.

Returns [AdminRole!]!

ArgumentTypeDescription
scopeStringsystem or tenant. Omit it to list roles of both scopes.

ssoLinkRequests​

Lists the sign-ins refused because they matched an existing identity with no link, oldest first, for a superuser to approve or reject. Requires user:read.

Returns [SsoLinkRequest!]!

tenantAgentActuation​

(Preview: may change in a minor release.) Agent actions in one tenant: whether this instance allows them, whether the operator has suspended them for the tenant, and the tenant's published agent policy version. Requires tenant:read.

Returns AdminTenantAgentActuation!

ArgumentTypeDescription
tenantString!(Preview: may change in a minor release.) Token of the tenant.

tenantDeletion​

The deletion record for one tenant token, with the progress of each storage system. Returns null if there is no such record. Requires tenant:read.

Returns TenantDeletion

ArgumentTypeDescription
epochStringThe epoch of the deletion, as returned in the epoch field, to select a particular past deletion. Omit it to get the deletion currently in progress for the token. It must be an RFC 3339 timestamp and is matched exactly, fractional seconds included.
tokenString!Token of the deleted tenant.

tenantDeletions​

Tenant deletion records, newest first, including those that have finished. They cover the whole instance and outlive the tenants they describe. Requires tenant:read.

Returns TenantDeletionSearchResults!

ArgumentTypeDescription
criteriaTenantDeletionSearchCriteria!Paging and an optional filter on whether the deletion has finished.

tenantTiers​

The tier catalog in the operator's listing order. Requires tenant:read.

Returns [AdminTenantTier!]!

tenants​

Every tenant, including any that are being deleted. The list is not paged. Requires tenant:read.

Returns [AdminTenant!]!

tierColorPalette​

The color names a tier may be given. Requires tenant:read.

Returns TierColorPalette!

Mutations​

addIdpDomain · addMembership · approveIdpDiscovery · approveSsoLinkRequest · clearPassword · createIdentity · createIdpConnection · createOauthClient · createRole · createTenant · createTenantTier · deleteIdentity · deleteIdpConnection · deleteOauthClient · deleteRole · deleteTenant · deleteTenantTier · linkIdentity · refreshIdpDiscovery · rejectSsoLinkRequest · removeIdpDomain · removeMembership · reorderTenantTiers · resetIdentityMfa · revokeSessions · rotateOauthClientSecret · setIdentityEnabled · setIdpCaBundle · setIdpConnectionSecret · setIdpConnectionTenants · setIdpJit · setIdpRequiredClaims · setIdpRoleMappings · setIdpSessionMaxAge · setMembershipEnabled · setMembershipRoles · setMembershipScope · setOauthClientEnabled · setPassword · setSystemRoles · setTenantAgentActuationSuspended · setTenantEnabled · setTenantMfaRequired · setTenantSsoEnforced · unlinkIdentity · updateIdpConnection · updateOauthClient · updateRole · updateTenant · updateTenantTier

addIdpDomain​

Asserts that a connection speaks for an email domain, recorded with your name, and returns the connection. Freemail providers and public suffixes are refused, and a domain belongs to one connection. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
domainString!The domain, for example example.com.
tokenString!Token of the connection.

addMembership​

Adds an identity to a tenant with the given tenant roles and returns the identity. The membership starts enabled. The roles may be instance roles with tenant scope or roles the tenant defined for itself. Fails if the identity or tenant does not exist, if the tenant is being deleted, if a role is not assignable in the tenant, if the scope has more than 16 anchors (LIMIT_EXCEEDED) or names a group (INVALID_VALUE), or if the identity is already a member of the tenant (error code CONFLICT). Requires user:write. Delegated callers must hold every authority granted by the assigned tenant roles (ESCALATION).

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
roleTokens[String!]!Tokens of the tenant roles to grant in the tenant.
scope[ScopeAnchorInput!]The customers to limit the membership to. Omit it, or send an empty list, for the whole tenant.
tenantString!Token of the tenant.

approveIdpDiscovery​

Approves the connection's current discovery snapshot and returns the connection. Fails if the snapshot is no longer the one with this fingerprint. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
fingerprintString!The fingerprint of the snapshot you reviewed.
tokenString!Token of the connection.

approveSsoLinkRequest​

Approves a pending link request: the external account is linked to the identity that has the request's email NOW. If that identity already holds memberships in the connection's tenants that no connection manages, say what becomes of them: convert makes the connection manage them, keep_manual leaves them. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns Boolean!

ArgumentTypeDescription
idID!Identifier of the request.
membershipDispositionStringconvert or keep_manual; required when the identity has such memberships.

clearPassword​

Removes an identity's password, so it can sign in only through single sign-on, and ends every session it has. Returns the identity. Fails if the identity does not exist, and is refused unless the identity is linked to an enabled connection it can sign in through (an instance connection for an identity holding a system role), so it is never left with no way in. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.

createIdentity​

Creates an identity with the given system roles and returns it. Fails if the email is already in use (error code CONFLICT), if the password is empty, or if a system role does not exist. Requires user:write. The caller may assign only system roles whose authorities it currently holds.

Returns AdminIdentity!

ArgumentTypeDescription
requestAdminIdentityCreateRequest!The identity to create.

createIdpConnection​

Creates an identity provider connection and returns it. The connection starts disabled and its discovery document is fetched (through the egress guard) and held for approval; review it with idpConnection, then approveIdpDiscovery and updateIdpConnection to enable it. Fails if this instance has no public issuer address ("sso requires a public issuer URL"), the token is taken, the issuer cannot be pinned to one organisation (Microsoft needs its tenant id and a tid requirement; Google needs an hd requirement), the provider cannot be reached, or an instance connection has neither required authentication methods nor mfaEnforcedByIdp. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
requestIdpConnectionCreateRequest!The connection to create.

createOauthClient​

Registers an OAuth client and returns it. The client starts enabled. For a confidential client the response also carries its secret, shown only this once. Fails if the clientId is invalid or already used (error code CONFLICT), or a redirect address or scope is not acceptable. Requires client:write.

Returns AdminOAuthClientSecret!

ArgumentTypeDescription
requestAdminOAuthClientCreateRequest!The client to register.

createRole​

Creates a role and returns it. Fails if the scope is not system or tenant, if an authority is unknown or belongs to the other scope, or if the token is already used in that scope (error code CONFLICT). Requires role:write. The caller must hold every authority the new role grants.

Returns AdminRole!

ArgumentTypeDescription
requestAdminRoleCreateRequest!The role to create.

createTenant​

Creates a tenant at the given tier and returns it. The tenant starts enabled. Fails if the tier does not exist, a limit is out of range, the token is already used by an active tenant (error code CONFLICT), or the token is reserved by a tenant that is still being deleted. Requires tenant:write.

Returns AdminTenant!

ArgumentTypeDescription
requestAdminTenantCreateRequest!The tenant to create.

createTenantTier​

Creates a tier and returns it. It is placed at display order 0. Fails if the config has an unknown key or an out-of-range value, if the color is not in the palette, or if the token is already used (error code CONFLICT). The catalog holds at most 100 tiers; a create beyond that is refused with error code LIMIT_EXCEEDED. Requires tenant:write.

Returns AdminTenantTier!

ArgumentTypeDescription
requestAdminTenantTierCreateRequest!The tier to create.

deleteIdentity​

Deletes an identity together with its memberships. Returns true if one was deleted and false if there was no such identity. Its sessions end with it, and an identity later created with the same email does not inherit them. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns Boolean!

ArgumentTypeDescription
emailString!Email of the identity.

deleteIdpConnection​

Deletes a connection together with its tenants, domains, links, pending requests and sealed client secret. Memberships it managed are disabled, not removed. Its sign-ins end at their next exchange; an identity token already issued for an instance connection keeps working on the admin API until it expires (15 minutes by default). Deleting the last enabled connection serving a tenant that requires single sign-on is refused with the error code SSO_ENFORCED_TENANT_STRANDED: turn the requirement off with setTenantSsoEnforced first. Returns true if it was deleted and false if there was no such connection. Requires user:write.

Returns Boolean!

ArgumentTypeDescription
tokenString!Token of the connection.

deleteOauthClient​

Deletes a client. Returns true if it was deleted and false if there was no such client. Requires client:write.

Returns Boolean!

ArgumentTypeDescription
clientIdString!The clientId of the client to delete.

deleteRole​

Deletes a role and removes it from everything it was assigned to. Returns true if it was deleted and false if there was no such role. The superuser system role cannot be deleted, so the instance cannot be locked out of this API. Requires role:write. The caller must hold every authority the current role grants.

Returns Boolean!

ArgumentTypeDescription
scopeString!system or tenant: the scope of the role to delete.
tokenString!Token of the role to delete.

deleteTenant​

Begins permanently deleting a tenant, which cannot be undone. Sign-ins and token refreshes for the tenant are refused at once for its members (a superuser can still enter, to operate the deletion), and its data is then erased from every storage system in the background; track that with tenantDeletion. Returning true means the deletion has started, not that the data is already gone. The tenant's token stays reserved until the deletion completes (see tenantDeletion). Returns false, changing nothing, if there is no such tenant or it is already being deleted. Fails (error code REFERENCE_VIOLATION) while any identity still has a membership in the tenant: remove the memberships first. Requires tenant:write.

Returns Boolean!

ArgumentTypeDescription
tokenString!Token of the tenant to delete.

deleteTenantTier​

Deletes a tier. Returns true if it was deleted and false if there was no such tier. Fails (error code REFERENCE_VIOLATION) while any tenant is still at the tier. Requires tenant:write.

Returns Boolean!

ArgumentTypeDescription
tokenString!Token of the tier to delete.

linkIdentity​

Links an external account to an identity: signing in at the provider as this subject signs in as this identity. This is how an instance connection reaches an identity. A tenant connection refuses an identity that holds a system role. Fails if the identity or connection does not exist, or either side is already linked. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns Boolean!

ArgumentTypeDescription
connectionString!Token of the connection.
emailString!Email of the identity.
subjectString!The external account's subject at the provider.

refreshIdpDiscovery​

Fetches the provider's discovery document again and returns the connection. If the endpoints changed, the new ones replace the snapshot and its approval is withdrawn: the connection refuses sign-ins until approveIdpDiscovery. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
tokenString!Token of the connection.

rejectSsoLinkRequest​

Rejects a pending link request, deleting it. Returns true if it existed. Requires user:write.

Returns Boolean!

ArgumentTypeDescription
idID!Identifier of the request.

removeIdpDomain​

Removes a domain from a connection and returns the connection. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
domainString!The domain to remove.
tokenString!Token of the connection.

removeMembership​

Removes an identity's membership in a tenant and returns the identity. This takes effect as disabling the membership does, at the identity's next token refresh. Fails if the identity has no membership in the tenant. Requires user:write. Delegated callers must hold every authority granted by the membership's current tenant roles (ESCALATION).

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
tenantString!Token of the tenant.

reorderTenantTiers​

Sets the listing order of the tiers and returns them in the new order. The list must name every existing tier exactly once; if it omits, repeats or invents a tier the request fails and nothing changes, which also catches a client working from a stale list. A list longer than 100 (the catalog's own bound), or a token longer than 128 characters, is refused with error code LIMIT_EXCEEDED. It changes only how tiers are ordered in lists, not what any tier grants. Requires tenant:write.

Returns [AdminTenantTier!]!

ArgumentTypeDescription
orderedTokens[String!]!Tokens of every tier, in the desired order, first to last.

resetIdentityMfa​

Removes an identity's two-factor authentication (a lost phone): the authenticator, the recovery codes and the stored secret go, every session the identity has ends, and the next password sign-in asks for no code. Returns the identity.

If the factor has wrong codes on record or is locked, the password may be in use by someone else, so newPassword is required and is set in the same step; without it the call fails with the error code MFA_RESET_NEEDS_PASSWORD and changes nothing. Resetting an identity that holds a system role needs a superuser caller. An identity with no second factor fails with an error. Requires user:write.

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
newPasswordStringA new password to set together with the reset. Required while the factor has failed attempts outstanding.

revokeSessions​

Ends every session an identity has, on every device: password and single sign-on, console, dashboard and MCP. Each ends at its next exchange; the access and identity tokens already issued stop working when they expire, 15 minutes by default (on the admin API too). The password is unchanged and the person can sign in again at once. Returns how many sign-ins it ended. Fails if the identity does not exist. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns Int!

ArgumentTypeDescription
emailString!Email of the identity.

rotateOauthClientSecret​

Generates a new secret for a client and returns it once, invalidating the previous secret. Rotating the secret of a public client makes it a confidential client. Fails if the client does not exist. Requires client:write.

Returns AdminOAuthClientSecret!

ArgumentTypeDescription
clientIdString!The clientId of the client.

setIdentityEnabled​

Enables or disables an identity and returns it. A disabled identity cannot sign in. Disabling also ends every session the identity has, so re-enabling does not revive them; tokens already issued stop working when they expire (15 minutes by default). Fails if the identity does not exist. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
enabledBoolean!True to enable, false to disable.

setIdpCaBundle​

Replaces a connection's private CA bundle and returns the connection; an empty bundle clears it, returning the connection to the system's trusted roots alone. A new bundle must verify the provider: its discovery document is fetched under it before anything is saved, and when that document names different endpoints than the approved ones the approval is withdrawn. The bundle is PEM text (up to 64 KiB of CERTIFICATE blocks); a private key is refused and never echoed. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
caBundleString!The PEM certificates, or an empty string to clear.
tokenString!Token of the connection.

setIdpConnectionSecret​

Stores a connection's client secret, replacing any earlier one, and returns the connection. The secret is write-only and can never be read back. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
secretString!The client secret.
tokenString!Token of the connection.

setIdpConnectionTenants​

Sets exactly which tenants a tenant connection serves, and returns it. Sign-ins through it can enter those tenants and no others. Fails for an instance connection or an unknown tenant, and refuses to drop a tenant that requires single sign-on when this is the last enabled connection serving it, with the error code SSO_ENFORCED_TENANT_STRANDED. Requires user:write. Requires holding every authority the connection's default roles and group mappings grant.

Returns IdpConnection!

ArgumentTypeDescription
tenants[String!]!Tokens of the tenants it serves.
tokenString!Token of the connection.

setIdpJit​

Sets whether a tenant connection creates identities at first sign-in (only for an address no identity has) and the tenant roles everyone who signs in through it holds, and returns the connection. An instance connection takes neither. A role with full authority needs acknowledgeFullAuthority. Requires user:write. Delegated callers must hold every authority granted by the default tenant roles and by the defaults being replaced (ESCALATION).

Returns IdpConnection!

ArgumentTypeDescription
acknowledgeFullAuthorityBooleanMust be true to grant a role with full authority to everyone.
connectionString!Token of the connection.
defaultTenantRoles[String!]!Tokens of the tenant roles every person holds in each tenant the connection serves.
enabledBoolean!Whether first sign-ins create identities.

setIdpRequiredClaims​

Replaces the claims every sign-in through the connection must carry, and returns the connection. The issuer rules still apply: a Google connection cannot drop hd nor a Microsoft one tid. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
claims[IdpClaimRequirementInput!]!The complete new list of required claims.
tokenString!Token of the connection.

setIdpRoleMappings​

Replaces a tenant connection's group-to-role mappings for one tenant it serves, and returns the connection. At each sign-in the person's membership in that tenant is recomputed: the connection's default roles plus the role of every mapping whose group they hold; none at all disables it. Only memberships the connection manages are touched, never manual ones. Roles are tenant roles only: a system role is refused. A role with full authority in the tenant needs acknowledgeFullAuthority. Takes effect at each person's next sign-in. Requires user:write. Delegated callers must hold every authority granted by the mapped tenant roles and by the mappings being replaced (ESCALATION).

Returns IdpConnection!

ArgumentTypeDescription
acknowledgeFullAuthorityBooleanMust be true to map a group to a role with full authority.
connectionString!Token of the connection.
mappings[IdpRoleMappingInput!]!The complete new set of mappings for the tenant.
tenantString!Token of the tenant; the connection must serve it.

setIdpSessionMaxAge​

Sets how long a session through a connection lasts, in seconds, and returns the connection. The allowed range is 900 (15 minutes) to 604800 (7 days); the upper bound is lower when the deployment's refresh token lifetime is shorter, and a value set before that lifetime was shortened is held to the new bound when sessions are checked. The lifetime counts from the moment this service accepted the sign-in and is never extended by a refresh. It applies to sessions already open, at their next exchange. Requires user:write.

Returns IdpConnection!

ArgumentTypeDescription
connectionString!Token of the connection.
secondsInt!The session lifetime in seconds.

setMembershipEnabled​

Enables or disables an identity's membership in a tenant and returns the identity. A disabled membership cannot be used to enter the tenant: disabling one takes effect at the identity's next token refresh (within 15 minutes; 5 for customer-scoped access), which is refused for this tenant, while an access token already issued keeps working until it expires. Its sessions in other tenants are not affected. Fails if the identity has no membership in the tenant. Requires user:write. Delegated callers must hold every authority granted by the membership's current tenant roles (ESCALATION).

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
enabledBoolean!True to enable, false to disable.
tenantString!Token of the tenant.

setMembershipRoles​

Replaces the tenant roles an identity holds in a tenant with exactly those given and returns the identity. Fails if the identity has no membership in the tenant or a role is not assignable in the tenant. Adding or taking away authorities takes effect at the identity's next token refresh (within 15 minutes; 5 for customer-scoped access): an access token already issued keeps its old authorities until it expires. Requires user:write. Delegated callers must hold every authority granted by both the current and assigned tenant roles (ESCALATION).

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
roleTokens[String!]!Tokens of the tenant roles the identity should hold in the tenant.
tenantString!Token of the tenant.

setMembershipScope​

Replaces the customers and groups a membership is limited to and returns the identity. An empty list gives the whole tenant. The change takes effect at the identity's next token refresh (within 15 minutes; 5 for customer-scoped access): an access token already issued keeps its old scope until it expires, and its sessions in other tenants are not affected. Fails if the identity has no membership in the tenant, or for more than 16 anchors (LIMIT_EXCEEDED). Requires user:write. Delegated callers must hold every authority granted by the membership's current tenant roles (ESCALATION).

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
scope[ScopeAnchorInput!]!The customers to limit the membership to; empty for the whole tenant.
tenantString!Token of the tenant.

setOauthClientEnabled​

Enables or disables a client and returns it. A disabled client is rejected at the authorization and token endpoints. Fails if the client does not exist. Requires client:write.

Returns AdminOAuthClient!

ArgumentTypeDescription
clientIdString!The clientId of the client.
enabledBoolean!True to enable, false to disable.

setPassword​

Replaces an identity's password and returns the identity. This also ends every session the identity has, so it must sign in again; tokens already issued stop working when they expire (15 minutes by default). Fails if the password is empty or the identity does not exist. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
passwordString!The new password. It must not be empty.

setSystemRoles​

Replaces the identity's system roles with exactly those given and returns the identity. An empty list removes them all. Fails if the identity does not exist or a role does not exist with system scope. Requires user:write. The caller must hold every authority granted by both the current and requested system roles.

Returns AdminIdentity!

ArgumentTypeDescription
emailString!Email of the identity.
roleTokens[String!]!Tokens of the system roles the identity should hold.

setTenantAgentActuationSuspended​

(Preview: may change in a minor release.) Suspends or restores agent actions for one tenant, whatever its own agent policy says. Suspended, no AI agent can be granted an action scope in the tenant and every agent decision there is a refusal. Restoring returns the tenant to its own policy. Requires tenant:write.

Returns AdminTenantAgentActuation!

ArgumentTypeDescription
suspendedBoolean!(Preview: may change in a minor release.) True to suspend agent actions in the tenant; false to restore its own policy.
tenantString!(Preview: may change in a minor release.) Token of the tenant.

setTenantEnabled​

Enables or disables a tenant and returns it. Members of a disabled tenant cannot enter it (a superuser still can); sessions already open are refused at their next refresh. Fails if the tenant does not exist. Requires tenant:write.

Returns AdminTenant!

ArgumentTypeDescription
enabledBoolean!True to enable, false to disable.
tokenString!Token of the tenant.

setTenantMfaRequired​

Requires (or stops requiring) a second factor of a tenant's password sign-ins and returns the tenant. While it is on, a member whose sign-in did not use a second factor is refused entry (error codes MFA_REQUIRED and MFA_ENROLLMENT_REQUIRED) and password sessions already inside are refused at their next refresh; a member can still sign in and set up their own authenticator, so nobody is stranded. Superusers are exempt and each of their entries is audited. It cannot turn off a requirement the tenant's tier sets. Requires user:write.

Returns AdminTenant!

ArgumentTypeDescription
requiredBoolean!Whether a second factor is required.
tenantString!Token of the tenant.

setTenantSsoEnforced​

Requires (or stops requiring) that a tenant's people sign in through single sign-on, and returns the tenant. Turning it on needs at least one enabled connection serving the tenant, so its people are not locked out (refused otherwise with the error code SSO_ENFORCE_NO_CONNECTION), and ends the password sessions already inside the tenant at their next refresh. Superusers are exempt and each of their entries is audited, so an identity provider outage never locks the operator out. Requires user:write.

Returns AdminTenant!

ArgumentTypeDescription
enforcedBoolean!Whether single sign-on is required.
tenantString!Token of the tenant.

unlinkIdentity​

Removes an identity's link on a connection; its sign-ins through that connection end at their next exchange. Returns true if a link was removed. Requires user:write. The caller must hold every authority granted by the identity's current system roles.

Returns Boolean!

ArgumentTypeDescription
connectionString!Token of the connection.
emailString!Email of the identity.

updateIdpConnection​

Applies a partial update to a connection and returns it. Enabling a connection needs its discovery snapshot approved. Disabling it ends its sessions at their next exchange: their refresh tokens stop working at once, and an access token already issued runs until it expires (15 minutes by default). An identity token already issued for an instance connection likewise keeps working on the admin API until it expires. Disabling the last enabled connection serving a tenant that requires single sign-on is refused with the error code SSO_ENFORCED_TENANT_STRANDED (its tenants extension names them): turn the requirement off with setTenantSsoEnforced first. Requires user:write. Changing a tenant connection's groupsClaim requires holding every authority its default roles and group mappings grant.

Returns IdpConnection!

ArgumentTypeDescription
requestIdpConnectionUpdateRequest!The changes to apply.
tokenString!Token of the connection.

updateOauthClient​

Applies a partial update to a client and returns it. Neither the redirect addresses nor the scopes may be emptied. Fails if the client does not exist or a value is not acceptable. Requires client:write.

Returns AdminOAuthClient!

ArgumentTypeDescription
clientIdString!The clientId of the client to update.
requestAdminOAuthClientUpdateRequest!The changes to apply.

updateRole​

Applies a partial update to a role and returns it. Fails if the role does not exist or the resulting authorities are not valid for its scope. Requires role:write. The caller must hold every authority granted by both the current and resulting role.

Returns AdminRole!

ArgumentTypeDescription
expectedUpdatedAtStringOptional updatedAt from the role being edited. A stale version refuses the save; omit for an unconditional update.
requestAdminRoleUpdateRequest!The changes to apply.
scopeString!system or tenant: the scope of the role to update.
tokenString!Token of the role to update.

updateTenant​

Applies a partial update to a tenant and returns it. If any value is invalid the whole update is rejected and nothing is changed. Fails if the tenant does not exist. Requires tenant:write.

Returns AdminTenant!

ArgumentTypeDescription
requestAdminTenantUpdateRequest!The changes to apply.
tokenString!Token of the tenant to update.

updateTenantTier​

Applies a partial update to a tier and returns it. This changes the limits of every tenant at the tier, taking effect within about a minute and without a deployment. Fails if the tier does not exist, the config has an unknown key or an out-of-range value, or the color is not in the palette. Requires tenant:write.

Returns AdminTenantTier!

ArgumentTypeDescription
requestAdminTenantTierUpdateRequest!The changes to apply.
tokenString!Token of the tier to update.

Objects​

AdminAuditEvent · AdminAuditEventSearchResults · AdminBurstSetting · AdminGovernanceDimension · AdminIdentity · AdminMembership · AdminOAuthClient · AdminOAuthClientSecret · AdminRateSetting · AdminRole · AdminTenant · AdminTenantAgentActuation · AdminTenantScalarSetting · AdminTenantSetting · AdminTenantTier · DeadLetter · DeadLetterSearchResults · IdpCaCertificate · IdpClaimRequirement · IdpConnection · IdpDiscovery · IdpDomain · IdpRoleMapping · ScopeAnchor · SearchResultsPagination · SsoLinkRequest · TenantDeletion · TenantDeletionSearchResults · TenantDeletionStore · TierColorPalette

AdminAuditEvent​

object

One entry in the instance's audit journal: either a sign-in or token refresh, or a change to one of this service's records (identities, roles, tenants, memberships and the like), including a tenant's own self-service changes. The journal covers the whole instance, not one tenant.

FieldTypeDescription
actorString!Who performed the action: the subject of the token that made the request, which is the user's email address for a person, system for an action the platform took itself, or an empty string when it was not recorded. Emptied for a tenant that has been deleted.
categoryString!auth for a sign-in or token refresh, or mutation for a change to stored data.
entityLabelStringA readable label for the changed record, such as a role or tenant token or an identity's email, when one is available. Null otherwise, and always cleared for a tenant that has been deleted, so the journal keeps the fact of the deletion but not what was deleted.
entityPkStringIdentifier of the changed record, when a single record was changed. Null otherwise.
idID!Server-assigned identifier of the entry.
occurredTimeString!When the event happened, as an RFC 3339 timestamp.
operationString!What happened: login, login_failed or refresh for an auth entry; create, update or delete for a mutation entry.
rowsAffectedInt!How many records the change affected.
tableNameStringQualified name of the stored collection that was changed. Null for an auth entry.
tenantStringToken of the tenant the entry belongs to. Null for events that belong to no tenant, such as signing in before a tenant is chosen.

AdminAuditEventSearchResults​

object

One page of audit journal entries, newest first.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits in the full result set.
results[AdminAuditEvent!]!The entries on this page, newest first.

AdminBurstSetting​

object

The burst allowance that applies to a tenant for one dimension, with where it came from. It is the same as AdminRateSetting except that a burst is a whole count.

FieldTypeDescription
overrideIntThe tenant's own override for this dimension. Null if it has none.
sourceString!Which level supplied the value: override, tier or platform-default, as for AdminRateSetting.
tierIntWhat the tenant's tier sets for this dimension. Null if the tier sets none.
valueIntThe burst allowance in force. Null when source is platform-default; null does not mean unlimited.

AdminGovernanceDimension​

object

A kind of usage the platform limits per tenant, expressed as a sustained rate plus a burst allowance. A tier or a tenant may set limits for each dimension.

FieldTypeDescription
burstFieldString!Name of the setting that holds this dimension's burst allowance, used the same way as rateField.
labelString!Human-readable heading for the dimension, such as "Ingest".
nameString!Short stable identifier of the dimension, such as ingest.
rateFieldString!Name of the setting that holds this dimension's rate. It is both the key used in a tier's config and the name of the matching field on tenants and tenant requests.
rateUnitString!The unit the rate is expressed in, such as readings/sec or requests/min. Bursts are plain counts of the same thing and carry no unit.

AdminIdentity​

object

A user account, which exists once across the whole instance and is identified by its email address. It can belong to any number of tenants through memberships.

FieldTypeDescription
createdAtStringWhen the identity was created, as an RFC 3339 timestamp.
emailString!The identity's email address, stored lower-cased. It is the sign-in name and cannot be changed.
enabledBoolean!False when the identity is disabled and cannot sign in.
firstNameStringFirst name. Null when none has been set.
idID!Server-assigned identifier. Address an identity by its email, not by this.
lastNameStringLast name. Null when none has been set.
memberships[AdminMembership!]!The tenants the identity belongs to, each with its roles there.
mfaEnabledBoolean!True when the identity has two-factor authentication turned on, so a password sign-in asks for a code. Reset it with resetIdentityMfa.
systemRoles[String!]!Tokens of the system roles the identity holds. System roles grant instance-level authorities, such as administering tenants or users, rather than authority inside a tenant.
updatedAtStringWhen the identity was last changed, as an RFC 3339 timestamp.

AdminMembership​

object

An identity's membership in one tenant: whether it is active and which tenant roles the identity holds there.

FieldTypeDescription
enabledBoolean!False when the membership is disabled, so the identity cannot enter the tenant through it.
roles[String!]!Tokens of the tenant-scoped roles the identity holds in this tenant.
scope[ScopeAnchor!]!The customers the membership is limited to inside the tenant. Empty when it sees the whole tenant.
tenantString!Token of the tenant.

AdminOAuthClient​

object

A client application registered to sign users in through the platform's OAuth 2.1 authorization flow. A client can only use the redirect addresses and scopes registered here. The client's secret is never readable.

FieldTypeDescription
clientIdString!The client's public identifier, as presented in authorization requests. It cannot be changed.
createdAtStringWhen the client was registered, as an RFC 3339 timestamp.
descriptionStringFree-text description. Null when none has been set.
enabledBoolean!False when the client is disabled; the authorization and token endpoints then reject it.
hasSecretBoolean!True for a confidential client, which authenticates with a secret. False for a public client, which authenticates with PKCE instead.
idID!Server-assigned identifier. Address a client by its clientId, not by this.
nameStringHuman-readable name. Null when none has been set.
redirectUris[String!]!The redirect addresses the client may use. A request must match one of them exactly.
scopes[String!]!The scopes the client may request.
updatedAtStringWhen the client was last changed, as an RFC 3339 timestamp.

AdminOAuthClientSecret​

object

The result of registering a client or rotating its secret. This is the only time the secret is shown.

FieldTypeDescription
clientAdminOAuthClient!The registered client as it now stands.
clientSecretStringThe client's secret in clear text, returned only in this response and stored only as a hash, so it cannot be retrieved again; keep it now. Null when the client is public.

AdminRateSetting​

object

The rate limit that applies to a tenant for one dimension, with where it came from, so you can see both the result and the levels behind it.

FieldTypeDescription
overrideFloatThe tenant's own override for this dimension. Null if it has none.
sourceString!Which level supplied the value: override (the tenant's own setting), tier (its tier's setting) or platform-default (neither sets one).
tierFloatWhat the tenant's tier sets for this dimension. Null if the tier sets none.
valueFloatThe rate in force, in the dimension's rate unit. Null when source is platform-default: each service applies its own built-in default, which this API does not report. Null does not mean unlimited.

AdminRole​

object

A named bundle of authorities that can be granted to identities. A system role carries instance-level authorities and is assigned to an identity; a tenant role carries authorities within one tenant and is assigned to a membership.

FieldTypeDescription
authorities[String!]!The authorities the role grants, such as device:write. The single value * grants every authority available at the role's scope. May be empty.
createdAtStringWhen the role was created, as an RFC 3339 timestamp.
descriptionStringFree-text description. Null when none has been set.
idID!Server-assigned identifier. Address a role by its scope and token, not by this.
nameStringHuman-readable name. Null when none has been set.
scopeString!Either system or tenant: who the role can be assigned to and which authorities it can grant.
tokenString!Identifier of the role, unique within its scope.
updatedAtStringWhen the role was last changed, as an RFC 3339 timestamp.

AdminTenant​

object

A tenant: an isolated customer environment that has its own devices and data. This is the operator's view of the tenant's registry entry, its limits and its deletion status.

FieldTypeDescription
aiExternalEnabledBooleanWhether the tenant has agreed to have its data sent to an external AI model provider. Null and false both mean it has not; only true allows it.
aiInferenceBurstIntThe tenant's own override of its AI inference burst allowance, in requests. Null means no override.
aiInferenceRequestsPerMinuteFloatThe tenant's own override of its sustained AI inference rate, in requests per minute. Null means no override: the tier's value applies, then the platform default; it never means unlimited.
configStringFree-form settings for the tenant as a JSON object serialized to a string. The platform stores it as given. Null when the tenant has none.
createdAtStringWhen the tenant was created, as an RFC 3339 timestamp.
effectiveScalarSettings[AdminTenantScalarSetting!]!What the tenant is actually limited to for each single-number setting that is not a rate and burst pair: the held-command ceiling, the shed priority and the three geofence limits. Each entry says which level set it, as effectiveSettings does.
effectiveSettings[AdminTenantSetting!]!What the tenant is actually limited to for each governance dimension, and which level set it. This is the result of applying the tenant's own overrides on top of its tier; use it to see the limit in force rather than to read the override fields.
enabledBoolean!False when the tenant is disabled. Members cannot enter a disabled tenant, though a superuser still can.
geoFenceCeilingIntThe tenant's own override of the most geofences it may have. Null means no override: the tier's value applies, then the platform default.
geoFencePositionBudgetIntThe tenant's own override of the most positions its geofences may have in total, summed across all fences. Null means no override: the tier's value applies, then the platform default.
geoFencePositionCeilingIntThe tenant's own override of the most positions one geofence may have, counted across all of its rings. Null means no override: the tier's value applies, then the platform default. It never means unlimited.
heldCommandCeilingIntThe tenant's own override of how many commands may be held waiting for offline devices. Null means no override: the tier's value applies, then the command service's default. It never means unlimited.
idID!Server-assigned identifier. Address a tenant by its token, not by this.
ingestBurstIntThe tenant's own override of its ingest burst allowance, in readings. Null means no override.
ingestReadingsPerSecondFloatThis tenant's own ingest ceiling override, in readings (decoded samples) per second. Null means the tenant inherits its tier's ceiling, then the platform default.
mfaRequiredBoolean!The tenant's own "second factor required" setting. The tenant's effective requirement is this OR its tier's mfaRequired floor (mfaRequiredByTier); either one makes a password sign-in without a second factor unable to enter the tenant. Single sign-on is governed by its connection's requirements instead, and the admin API is never gated on it. Change it with setTenantMfaRequired.
mfaRequiredByTierBoolean!True when the tenant's tier requires a second factor, which no tenant setting can turn off.
nameStringHuman-readable name. Null when none has been set.
outboundBurstIntThe tenant's own override of its outbound burst allowance, in calls. Null means no override.
outboundCallsPerSecondFloatThis tenant's own outbound ceiling override, in connector calls dispatched per second. Null means the tenant inherits its tier's ceiling, then the platform default.
provisioningBurstIntThe tenant's own override of its self-registration burst allowance, in registrations. Null means no override.
provisioningRegistrationsPerSecondFloatThe tenant's own override of its sustained device self-registration rate, in registrations per second. Null means no override: the tier's value applies, then the platform default; it never means unlimited.
purgeEpochStringWhen deletion of the tenant was requested, as an RFC 3339 timestamp. Null while the tenant is active. Together with the token it identifies this deletion in tenantDeletion.
purgeStateString!Where the tenant is in its deletion lifecycle: active normally, or purging once deleteTenant has been called. A purging tenant stays in the registry, and keeps its token reserved, until the deletion completes: its data erased everywhere and the settling and token-hold periods over; the entry then disappears.
shedPriorityIntThe tenant's own override of its overload-protection priority, a whole number from 1 to 100, higher meaning the tenant's traffic is refused later when the platform is overloaded. Null means no override: the tier's value applies, then the platform default.
ssoEnforcedBoolean!Whether the tenant's people must sign in through single sign-on. While true, a session that began with a password cannot enter the tenant (at sign-in, tenant selection, refresh or an MCP authorization), and the password sign-in does not list the tenant. A superuser is exempt and each of their entries is audited. Change it with setTenantSsoEnforced.
tierAdminTenantTier!The tier the tenant is packaged at. Every tenant has exactly one.
tokenString!Unique identifier of the tenant on this instance. It cannot be changed.
updatedAtStringWhen the tenant was last changed, as an RFC 3339 timestamp.

AdminTenantAgentActuation​

object

(Preview: may change in a minor release.) Agent actions in one tenant, as the instance operator sees them. Agents can act in a tenant only when this instance allows agent actions, the operator has not suspended them for the tenant, and the tenant's own published agent policy enables them.

FieldTypeDescription
instanceEnabledBoolean!(Preview: may change in a minor release.) True when this instance allows agent actions at all.
publishedVersionInt!(Preview: may change in a minor release.) The tenant's published agent policy version, or 0 when it has published none.
suspendedBoolean!(Preview: may change in a minor release.) True when the operator has suspended agent actions for this tenant.
suspendedAtString(Preview: may change in a minor release.) When the suspension was set, as an RFC 3339 timestamp, or null.
suspendedByString(Preview: may change in a minor release.) Who set the suspension, or null.
tenantString!(Preview: may change in a minor release.) Token of the tenant.

AdminTenantScalarSetting​

object

The value in force for a tenant on one single-number setting, with where it came from, so you can see both the result and the levels behind it. It has the same shape as AdminBurstSetting, plus the setting's key and label.

FieldTypeDescription
keyString!Name of the setting, such as heldCommandCeiling. It is both the key used in a tier's config and the name of the matching override field on tenants.
labelString!Human-readable heading for the setting, such as "Shed priority".
overrideIntThe tenant's own override for this setting. Null if it has none.
sourceString!Which level supplied the value: override (the tenant's own setting), tier (its tier's setting) or platform-default (neither sets one).
tierIntWhat the tenant's tier sets for this setting. Null if the tier sets none.
valueIntThe value in force. Null when source is platform-default: the enforcing service applies its own built-in default, which this API does not report. Null does not mean unlimited.

AdminTenantSetting​

object

The limits in force for a tenant on one governance dimension.

FieldTypeDescription
burstAdminBurstSetting!The burst allowance.
dimensionAdminGovernanceDimension!The dimension these limits apply to.
rateAdminRateSetting!The sustained rate limit.

AdminTenantTier​

object

A named packaging level, such as gold, silver or bronze, that an operator assigns to tenants. A tier supplies default limits for the tenants at it, and a tenant's own settings override them. Editing a tier changes every tenant at it.

FieldTypeDescription
colorStringName of the color the console shows for this tier, one of those listed by tierColorPalette, or null for no color. Presentation only.
configStringThe tier's settings as a JSON object serialized to a string, or null when it has none. The keys are the governance setting names listed by governanceDimensions (the rate and burst fields) together with shedPriority, heldCommandCeiling, geoFencePositionCeiling, geoFenceCeiling and geoFencePositionBudget. A tenant that has no setting of its own for a key takes the tier's value.
createdAtStringWhen the tier was created, as an RFC 3339 timestamp.
descriptionStringFree-text description of the tier. Null when none has been set.
displayOrderInt!Position of the tier in the operator's listing order, counting up from 0. It only orders lists: a higher position does not make a tier a superset of a lower one. A new tier starts at 0 and tiers with the same position are listed alphabetically by token, until the order is set with reorderTenantTiers.
idID!Server-assigned identifier. Address a tier by its token, not by this.
nameStringHuman-readable name of the tier. Null when none has been set.
tenantCountInt!The number of active tenants at this tier, not counting tenants being deleted. A tier cannot be deleted while any tenant, including one still being deleted, is at it.
tokenString!Unique identifier of the tier.
updatedAtStringWhen the tier was last changed, as an RFC 3339 timestamp.

DeadLetter​

object

A unit of work the platform accepted and then gave up on, recorded so that the failure can be seen and diagnosed. The record is informational: the work is not retried from it, and the consequence of the failure stands.

FieldTypeDescription
attemptsInt!How many delivery attempts were made before giving up.
correlationStringIdentifier of the request the work belonged to, for matching against logs. Null when not recorded.
detailStringThe underlying error text. It can name destinations a tenant configured, so treat it as operator-only. Null when there is nothing to add.
idID!Server-assigned identifier of the record, as accepted by the deadLetter query.
kindString!What kind of work was given up on: detection-action, notification, command-response, connector-dispatch, event, command or control-fact. For connector-dispatch the record is only an index entry, with no copy of the request.
occurredTimeString!When the platform gave up, as an RFC 3339 timestamp.
reasonString!Why the work was given up on: exhausted (retried up to the limit), unprocessable (accepted, but can never be completed), shed (refused because the tenant stayed over its rate limit for too long; the work itself was fine and was never attempted) or no-outcome (every delivery ended without an outcome being recorded, so the work may in fact have happened).
referenceStringIdentifier of the specific thing that failed within its kind, such as a rule, alarm or command token. Null when not recorded.
sequenceStringPosition of the original message in its stream, as a decimal string because the value can exceed what a GraphQL Int holds. Null when not recorded.
sourceString!Name of the functional area that gave up.
subjectStringWhere the original message was published, for locating it while the platform still retains it. Null when not recorded.
summaryString!A fixed sentence describing the class of failure. Safe to show to anyone.
tenantString!Token of the tenant whose work this was.

DeadLetterSearchResults​

object

One page of dead letters, newest first.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits in the full result set.
results[DeadLetter!]!The records on this page, newest first.

IdpCaCertificate​

object

One certificate of a connection's private CA bundle.

FieldTypeDescription
fingerprintSha256String!SHA-256 fingerprint of the certificate, in hex; compare it with the one your CA publishes.
isCaBoolean!Whether the certificate says it is a certificate authority. A certificate that is not one is accepted (it pins that exact certificate) but is usually not what was meant.
issuerString!Issuer distinguished name.
notAfterString!End of the validity period. The provider cannot be reached once the root it chains to has expired.
notBeforeString!Start of the validity period.
subjectString!Subject distinguished name.

IdpClaimRequirement​

object

A claim a sign-in must carry, with the value it must have.

FieldTypeDescription
nameString!Claim name.
valueString!Required value.

IdpConnection​

object

An identity provider connection: an external OpenID Connect provider that people sign in through. The provider's client secret is write-only and is never returned.

FieldTypeDescription
caCertificates[IdpCaCertificate!]!The certificates of the private CA bundle this provider's TLS certificate is verified against, in addition to the system's trusted roots. Empty when none is set.
callbackUrlString!The address to register at the provider as this connection's redirect (callback) URI.
clientIdString!The client identifier registered at the provider.
createdAtStringWhen the connection was created.
defaultTenantRoles[String!]!Tokens of the tenant roles everyone who signs in through the connection holds in each tenant it serves.
discoveryIdpDiscovery!The provider's discovery document as last fetched; sign-ins use only the endpoints approved here.
domains[IdpDomain!]!Email domains this connection speaks for.
emailClaimString!Name of the claim carrying the person's email address.
enabledBoolean!Whether sign-ins through this connection are accepted. A connection is created disabled.
groupsClaimString!Name of the claim carrying the person's group values, which role mappings match. Only a tenant connection reads it.
hasSecretBoolean!Whether a client secret is stored. The secret itself can never be read.
issuerString!The provider's issuer. Fixed when the connection is created.
jitEnabledBoolean!Whether a first sign-in creates an identity for a person no identity has the address of. An address that already has an identity is never linked automatically: it leaves a link request.
kindString!Whose provider this is: tenant for a provider that serves one or more tenants' own people (its sign-ins can enter only those tenants and can never reach an identity holding a system role), or instance for the operator's own provider (linked to identities only by explicit action, and entering a tenant only as a superuser).
nameString!Display name.
providerSignOutBoolean!Whether signing out also signs the person out at the provider, through its approved sign-out endpoint. Off unless switched on with updateIdpConnection: signing out at the provider ends the person's session there for every application it serves. Has no effect while the approved discovery document names no sign-out endpoint.
requiredAmr[String!]!Authentication methods of which a sign-in must report at least one; empty for none required.
requiredClaims[IdpClaimRequirement!]!Claims every sign-in must carry with exactly these values.
roleMappings[IdpRoleMapping!]!The group-to-role mappings, across the tenants the connection serves.
scopes[String!]!OAuth scopes requested at sign-in.
sessionMaxAgeSecondsInt!How long a session through this connection lasts, in seconds, counted from the moment this service accepted the sign-in (not the provider's own authentication time) and never extended by a refresh. When it passes, the session ends at its next exchange and the person signs in again. 12 hours (43200) unless changed with setIdpSessionMaxAge.
signOutReturnUrls[String!]!The addresses to register at the provider as post-logout redirect URIs, one per app (the console's sign-in page and the dashboard app), for signing out at the provider. Empty when the instance has no public address.
tenants[String!]!Tokens of the tenants a tenant connection serves; empty for an instance connection.
tokenString!Short unique token of the connection; it appears in the connection's callback address.
updatedAtStringWhen the connection was last changed.

IdpDiscovery​

object

The endpoints a connection will use, as fetched from the provider's discovery document.

FieldTypeDescription
approvedBoolean!Whether a person has approved these endpoints. Sign-ins are refused until they have.
approvedAtStringWhen they were approved.
approvedByStringWho approved them.
authorizationEndpointString!The authorization endpoint.
endSessionEndpointStringThe provider's sign-out endpoint, when it has one.
fetchedAtStringWhen the document was fetched.
fingerprintString!Identifies this exact set of endpoints; pass it to approveIdpDiscovery to approve what you reviewed.
jwksUriString!The address of the provider's signing keys.
tokenEndpointString!The token endpoint.

IdpDomain​

object

An email domain asserted for a connection.

FieldTypeDescription
domainString!The domain, lower-case ASCII.
verifiedAtString!When it was asserted.
verifiedByString!Who asserted it.

IdpRoleMapping​

object

A mapping from a provider group to a tenant role, within one tenant a connection serves.

FieldTypeDescription
fullAuthorityBoolean!Whether the role carries the tenant's super-authority.
groupString!The group value in the provider's groups claim.
roleString!Token of the tenant role members of the group hold.
tenantString!Token of the tenant.

ScopeAnchor​

object

One entry of a membership's scope: a customer or group whose devices the member can see.

FieldTypeDescription
kindScopeAnchorKind!What the anchor names.
tokenString!Token of the customer (or group) the anchor names.

SearchResultsPagination​

object

Where a page of search results sits in the full result set. Positions are 1-based and inclusive.

FieldTypeDescription
pageEndIntPosition of the last result on this page within the full result set (1-based, inclusive).
pageStartIntPosition of the first result on this page within the full result set (1-based).
totalRecordsIntNumber of records matching the criteria across all pages.

SsoLinkRequest​

object

A sign-in that was refused because it matched an existing identity with no link. It grants nothing.

FieldTypeDescription
connectionString!Token of the connection the sign-in came through.
createdAtStringWhen the sign-in was refused.
emailString!The email address the provider asserted.
idID!Identifier of the request.
identityExistsBoolean!Whether an identity with that email exists now.
manualMemberships[String!]!Tenants this connection serves where the identity already has a membership that no connection manages.
subjectString!The external account's subject at the provider.
subjectChangedBoolean!True when that identity is already linked on this connection under a different subject, which is what a recycled email address looks like.

TenantDeletion​

object

The durable record of one tenant deletion. It outlives the tenant: once the deletion completes the tenant is gone, and this record is the evidence that its data was erased. It deliberately holds no tenant name.

FieldTypeDescription
awaitingDeletionWait!What the deletion is currently waiting on.
blockedBy[String!]!One sentence for each storage system that is not yet clean, in that system's own words. Empty means nothing is blocking, which is not the same as finished: the deletion may still be waiting out a settling period or the token hold.
completedAtStringWhen every storage system had reported clean and the token was released, as an RFC 3339 timestamp. Null while the deletion is in progress.
elapsesAtStringWhen the current waiting period ends, as an RFC 3339 timestamp. Null when the wait is not a timed period: while awaiting is STORES the deletion waits on the systems, not on a clock, and when awaiting is NONE nothing is pending.
epochString!When the deletion was requested, as an RFC 3339 timestamp with fractional seconds. With the token it identifies the record; pass it back exactly as returned.
erasedBoolean!True when the tenant's data is established as erased (erasedAt is set) or the deletion has completed. False means erasure is not established: a deletion that is partial is not erased.
erasedAtStringWhen the deletion's data was first established as erased, as an RFC 3339 timestamp: every storage system had reported clean, continuously for the settling period, as of that pass. This comes before completedAt, because the token is held for a further period after the data is gone. Null while any storage system still holds data. The claim is withdrawn, and this returns to null, if a storage system reports data again before the deletion completes.
lastVerifiedAtStringWhen the latest coordinator pass re-confirmed the erasure claim, as an RFC 3339 timestamp: every storage system reported clean, continuously for the settling period, as of that pass. Null whenever erasedAt is. The claim can be withdrawn until the deletion completes (completedAt), so this says how fresh it is; it is final only at completedAt.
retainedAuditTenantString!The tenant value the deleted tenant's audit journal entries are kept under: the token and the epoch joined by ~. The entries are kept as evidence of the deletion, with the names in them removed, and are moved off the token so that a new tenant created later with the same token does not see them. Pass this as the tenant filter of auditEvents to read them.
rowsErasedInt!Total number of records erased across all storage systems.
stores[TenantDeletionStore!]!One line per storage system, ordered by name.
tokenString!Token of the deleted tenant. A token can be reused after a deletion finishes, so it identifies a deletion only together with epoch.

TenantDeletionSearchResults​

object

One page of tenant deletion records, newest first.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits in the full result set.
results[TenantDeletion!]!The deletion records on this page, newest first.

TenantDeletionStore​

object

One storage system's line in a tenant deletion's progress record.

FieldTypeDescription
attemptedAtStringWhen this storage system was last checked, as an RFC 3339 timestamp. Null if it has not been checked yet.
cleanSinceStringWhen this storage system first reported clean and has stayed clean on every check since, as an RFC 3339 timestamp. Null unless it is clean now.
completeBoolean!True once this storage system has reported that it holds nothing for the tenant.
lastErrorStringA sentence describing why the latest pass could not confirm this storage system is clean. Null when it succeeded. Unlike retaining, this is expected to clear by itself on a later pass.
noteStringA sentence describing something this storage system deliberately did not examine, or why it reported clean while erasing nothing, such as a store that does not exist on this instance. It qualifies a clean result and is not a problem to act on.
retainingStringA sentence describing data this storage system still holds and has not erased. Null means it holds nothing outstanding. While set it blocks the deletion from finishing and does not clear by itself; something has to change first.
rowsErasedInt!How much this storage system has erased so far, in records, counted across all passes. It shows that erasure ran; it is not a percentage of progress.
storeString!Short key of the storage system this line reports on, such as rdb for the relational database or blob for the object store.

TierColorPalette​

object

The fixed set of color names a tier may be given.

FieldTypeDescription
colors[String!]!The color names, in the order a picker should present them.

Input types​

AdminAuditEventSearchCriteria · AdminIdentityCreateRequest · AdminOAuthClientCreateRequest · AdminOAuthClientUpdateRequest · AdminRoleCreateRequest · AdminRoleUpdateRequest · AdminTenantCreateRequest · AdminTenantTierCreateRequest · AdminTenantTierUpdateRequest · AdminTenantUpdateRequest · DeadLetterSearchCriteria · IdpClaimRequirementInput · IdpConnectionCreateRequest · IdpConnectionUpdateRequest · IdpRoleMappingInput · ScopeAnchorInput · TenantDeletionSearchCriteria

AdminAuditEventSearchCriteria​

input

Filters and paging for searching the audit journal. Every filter is optional and filters are combined with AND.

Input fieldTypeDescription
actorStringOnly entries whose actor contains this text. The match ignores case. At most 256 bytes; longer input is refused with LIMIT_EXCEEDED.
categoryStringOnly entries of this category, auth or mutation. Exact match.
endTimeStringOnly entries at or before this time, as an RFC 3339 timestamp.
operationStringOnly entries of this operation, such as login or update. Exact match.
pageNumberInt!Page to return, starting at 1.
pageSizeInt!Results per page. Below 1 means the default of 100; above 1000 is capped at 1000.
startTimeStringOnly entries at or after this time, as an RFC 3339 timestamp.
tenantStringOnly entries belonging to the tenant with this token. Exact match. Entries that belong to no tenant are excluded when this is set. A deleted tenant's entries are kept under its deletion's retainedAuditTenant, not under its token.

AdminIdentityCreateRequest​

input

Fields for a new identity.

Input fieldTypeDescription
emailString!The identity's email address. It becomes the sign-in name, is stored lower-cased and cannot be changed. It must not already be in use.
enabledBoolean!Whether the identity may sign in. Send false to create it disabled.
firstNameStringGiven name, shown in the console. A blank value is stored as unset.
lastNameStringFamily name, shown in the console. A blank value is stored as unset.
passwordString!The initial password. It must not be empty. It is stored hashed and cannot be read back.
systemRoles[String!]!Tokens of the system roles to assign. Each must name an existing role with system scope; an empty list assigns none.

AdminOAuthClientCreateRequest​

input

Fields for registering an OAuth client.

Input fieldTypeDescription
clientIdString!The client's public identifier: letters, digits, -, _ and ., at most 128 characters. It cannot be changed.
confidentialBooleanTrue to register a confidential client, for which a secret is generated and returned once. False or omitted registers a public client that uses PKCE.
descriptionStringFree-text description.
nameStringHuman-readable name.
redirectUris[String!]!The redirect addresses the client may use; at least one and at most 16, each at most 2048 characters. Each must be an absolute https URL with no fragment and no embedded credentials. Plain http is accepted only for loopback hosts (localhost, 127.0.0.1, ::1). A longer list or entry is refused with error code LIMIT_EXCEEDED.
scopes[String!]!The scopes the client may request; at least one and at most 16, each at most 64 characters. Supported scopes are read-only and location. A longer list or entry is refused with error code LIMIT_EXCEEDED.

AdminOAuthClientUpdateRequest​

input

A partial update to an OAuth client. Omit a field to keep it, send a value to set it, or send null to clear it. The client is named by the mutation's clientId argument, which cannot be changed.

Input fieldTypeDescription
descriptionStringNew description, or null to clear it.
nameStringNew name, or null to clear it.
redirectUris[String!]The complete new list of redirect addresses, replacing the current list and validated as for registration, including its bounds (at most 16, each at most 2048 characters; more is refused with error code LIMIT_EXCEEDED). It cannot be emptied: null or an empty list is rejected, so to keep the list unchanged omit the field.
scopes[String!]The complete new list of scopes the client may request, replacing the current list and validated as for registration, including its bounds (at most 16, each at most 64 characters; more is refused with error code LIMIT_EXCEEDED). It cannot be emptied: null or an empty list is rejected, so to keep the list unchanged omit the field.

AdminRoleCreateRequest​

input

Fields for a new role.

Input fieldTypeDescription
authorities[String!]!The authorities to grant, as listed by the authorities query for the same scope; * is allowed at either scope. An unknown authority, or one that belongs to the other scope, rejects the request. An empty list creates a role that grants nothing.
descriptionStringFree-text description.
nameStringHuman-readable name.
scopeString!system or tenant. A role's scope cannot be changed afterwards.
tokenString!Identifier for the role, unique within its scope.

AdminRoleUpdateRequest​

input

A partial update to a role. Omit a field to keep it, send a value to set it, or send null to clear it. The role is named by the mutation's scope and token arguments, which cannot be changed.

Input fieldTypeDescription
authorities[String!]The complete new set of authorities, replacing the current set. Null and an empty list both leave the role granting nothing. Validated as for creation; an unknown authority, or one that belongs to the other scope, rejects the whole update.
descriptionStringNew description, or null to clear it.
nameStringNew name, or null to clear it.

AdminTenantCreateRequest​

input

Fields for a new tenant.

Input fieldTypeDescription
aiExternalEnabledBooleanRecords the tenant's agreement to have its data sent to an external AI model provider. Omit it for not agreed.
aiInferenceBurstIntOverride of the AI inference burst allowance, in requests. Must be positive. Omit to inherit.
aiInferenceRequestsPerMinuteFloatOverride of the sustained AI inference rate in requests per minute. Must be positive. Omit to inherit.
configStringFree-form settings as a JSON object serialized to a string. Omit it, or send an empty string or {}, for none.
geoFenceCeilingIntOverride of the most geofences the tenant may have. A positive whole number of at most 4000; a larger value is rejected, not clamped. Omit to inherit.
geoFencePositionBudgetIntOverride of the most positions the tenant's geofences may have in total. A positive whole number of at most 128000; a larger value is rejected, not clamped. Omit to inherit.
geoFencePositionCeilingIntOverride of the most positions one geofence may have, across all of its rings. A positive whole number of at most 1024; a larger value is rejected, not clamped. Omit to inherit.
heldCommandCeilingIntOverride of how many commands may be held waiting for offline devices. Any positive whole number. Omit to inherit the tier's value, then the command service's default.
ingestBurstIntOverride of the ingest burst allowance, in readings. Must be positive. Omit to inherit.
ingestReadingsPerSecondFloatIngest ceiling override, in readings (decoded samples) per second. Must be positive; omit it to inherit the tier's ceiling, then the platform default.
nameStringHuman-readable name.
outboundBurstIntOverride of the outbound burst allowance, in calls. Must be positive. Omit to inherit.
outboundCallsPerSecondFloatOutbound ceiling override, in connector calls dispatched per second. Must be positive; omit it to inherit the tier's ceiling, then the platform default.
provisioningBurstIntOverride of the self-registration burst allowance, in registrations. Must be positive. Omit to inherit.
provisioningRegistrationsPerSecondFloatOverride of the sustained device self-registration rate, in registrations per second. Must be positive. Omit to inherit the tier's value, then the platform default.
shedPriorityIntOverride of the overload-protection priority: a whole number from 1 to 100, higher meaning the tenant's traffic is refused later when the platform is overloaded; 80 to 100 is never refused. Omit to inherit the tier's value, then the platform default.
tierTokenString!Token of the tier to package the tenant at. The tier must exist.
tokenString!Unique identifier for the tenant: letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters. It cannot be changed. A token that belongs to a tenant being deleted is reserved and is refused until that deletion finishes.

AdminTenantTierCreateRequest​

input

Fields for a new tenant tier.

Input fieldTypeDescription
colorStringA color name from tierColorPalette. Omit it, or send null or an empty string, for no color; an unknown name rejects the request.
configStringThe tier's settings as a JSON object serialized to a string, using the keys described on AdminTenantTier.config. An unknown key, or a value outside its allowed range, rejects the request. Omit it, or send an empty string or {}, for a tier with no settings.
descriptionStringFree-text description.
nameStringHuman-readable name.
tokenString!Unique identifier for the tier: letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters.

AdminTenantTierUpdateRequest​

input

A partial update to a tier. Omit a field to keep it, send a value to set it, or send null to clear it. The tier is named by the mutation's token argument. Changes apply to every tenant at the tier.

Input fieldTypeDescription
colorStringA color name from tierColorPalette, trimmed of surrounding spaces. Null or an empty string clears it; an unknown name rejects the request.
configStringThe tier's settings as a JSON object serialized to a string, replacing the current settings entirely. Null, an empty string or {} removes all of them, so every tenant at the tier then falls back to the platform defaults. An unknown key, or a value outside its allowed range, rejects the request.
descriptionStringNew description, or null to clear it.
nameStringNew name, or null to clear it.

AdminTenantUpdateRequest​

input

A partial update to a tenant. For every field, omitting it keeps the stored value, sending a value sets it, and sending null clears it. Clearing a limit removes the tenant's own override, so the tier's value applies, then the platform default; it never makes the tenant unlimited. The tenant is named by the mutation's token argument. Limits are validated as for creation.

Input fieldTypeDescription
aiExternalEnabledBooleanWhether the tenant has agreed to have its data sent to an external AI model provider. Null clears the record, which counts as not agreed.
aiInferenceBurstIntOverride of the AI inference burst allowance, in requests. Must be positive.
aiInferenceRequestsPerMinuteFloatOverride of the sustained AI inference rate, in requests per minute. Must be positive.
configStringFree-form settings as a JSON object serialized to a string, replacing the current ones. Null, an empty string or {} clears them.
geoFenceCeilingIntOverride of the most geofences the tenant may have. A positive whole number of at most 4000.
geoFencePositionBudgetIntOverride of the most positions the tenant's geofences may have in total. A positive whole number of at most 128000.
geoFencePositionCeilingIntOverride of the most positions one geofence may have. A positive whole number of at most 1024.
heldCommandCeilingIntOverride of how many commands may be held waiting for offline devices. A positive whole number.
ingestBurstIntOverride of the ingest burst allowance, in readings. Must be positive. Omitted leaves it as it is; null removes it so the tenant inherits.
ingestReadingsPerSecondFloatIngest ceiling override, in readings (decoded samples) per second. Omitted leaves it as it is; null removes it so the tenant inherits; a value must be positive.
nameStringNew name, or null to clear it.
outboundBurstIntOverride of the outbound burst allowance, in calls. Must be positive. Omitted leaves it as it is; null removes it so the tenant inherits.
outboundCallsPerSecondFloatOutbound ceiling override, in connector calls dispatched per second. Omitted leaves it as it is; null removes it so the tenant inherits; a value must be positive.
provisioningBurstIntOverride of the self-registration burst allowance, in registrations. Must be positive. Omitted leaves it as it is; null removes it so the tenant inherits.
provisioningRegistrationsPerSecondFloatOverride of the sustained device self-registration rate, in registrations per second. Must be positive. Omitted leaves it as it is; null removes it so the tenant inherits.
shedPriorityIntOverride of the overload-protection priority, a whole number from 1 to 100.
tierTokenStringToken of the tier to move the tenant to; the change takes effect within about a minute. Omit it to keep the current tier. Null is rejected, because every tenant has a tier.

DeadLetterSearchCriteria​

input

Filters and paging for searching dead letters. Every filter is optional and filters are combined with AND.

Input fieldTypeDescription
kindStringOnly records of this kind. Exact match.
pageNumberInt!Page to return, starting at 1.
pageSizeInt!Results per page. Below 1 means the default of 100; above 1000 is capped at 1000.
sinceStringOnly records that occurred at or after this time, as an RFC 3339 timestamp. A value that cannot be parsed is an error, not ignored.
sourceStringOnly records from this functional area. Exact match.
tenantStringOnly records for the tenant with this token. Exact match.
untilStringOnly records that occurred at or before this time, as an RFC 3339 timestamp. A value that cannot be parsed is an error, not ignored.

IdpClaimRequirementInput​

input

A claim requirement to set on a connection.

Input fieldTypeDescription
nameString!Claim name, for example hd or tid.
valueString!Required value.

IdpConnectionCreateRequest​

input

Data to create a connection.

Input fieldTypeDescription
caBundleStringPEM text of private CA certificates to trust, besides the system's roots, for this provider's TLS certificate (an on-premises provider whose certificate a private CA signed). Up to 64 KiB of CERTIFICATE blocks; a private key is refused. The provider's discovery document must be reachable under it.
clientIdString!The client identifier registered at the provider.
clientSecretStringThe client secret. Write-only; leave out for a public client.
emailClaimStringName of the claim carrying the email address; defaults to email.
groupsClaimStringName of the claim carrying group values; defaults to groups.
issuerString!The provider's issuer, an https address. A shared multi-tenant issuer must be pinned to your organisation by a required claim.
kindString!tenant or instance.
mfaEnforcedByIdpBooleanFor an instance connection with no required authentication methods: your statement that the provider enforces multi-factor sign-in. It is recorded in the audit journal.
nameString!Display name.
requiredAmr[String!]Authentication methods of which a sign-in must report at least one.
requiredClaims[IdpClaimRequirementInput!]Claims every sign-in must carry with exactly these values (Google needs hd, Microsoft needs tid).
scopes[String!]OAuth scopes to request; defaults to openid, email and profile.
tokenString!Short unique token for the connection (letters, digits and hyphens).

IdpConnectionUpdateRequest​

input

Changes to a connection. A partial update: leaving a field out keeps its stored value. The issuer, kind and token cannot be changed.

Input fieldTypeDescription
clientIdStringNew client identifier.
emailClaimStringNew email claim name.
enabledBooleanTrue to accept sign-ins through the connection; enabling needs approved discovery.
groupsClaimStringNew groups claim name.
nameStringNew display name.
providerSignOutBooleanTrue to sign people out at the provider too when they sign out; see IdpConnection.providerSignOut.
requiredAmr[String!]The complete new list of required authentication methods.
scopes[String!]The complete new list of scopes.

IdpRoleMappingInput​

input

One group-to-role mapping to set.

Input fieldTypeDescription
groupString!The group value in the provider's groups claim.
roleString!Token of a tenant role. System roles are refused.

ScopeAnchorInput​

input

One entry of a scope to set on a membership.

Input fieldTypeDescription
kindScopeAnchorKind!What the anchor names.
tokenString!Token of the customer or group the anchor names.

TenantDeletionSearchCriteria​

input

Paging and an optional completion filter for listing tenant deletions.

Input fieldTypeDescription
completedBooleanTrue for deletions that have finished, false for those still in progress. Omit it for both.
pageNumberInt!Page to return, starting at 1.
pageSizeInt!Results per page. Below 1 means the default of 100; above 1000 is capped at 1000.

Enums​

DeletionWait · ScopeAnchorKind

DeletionWait​

enum

What a tenant deletion is currently waiting on.

ValueDescription
STORESAt least one storage system has not reported clean. This is the only wait that needs a person; blockedBy says which system and why.
SETTLEEvery storage system is clean but has not yet stayed clean for the required settling period.
TOKEN_HOLDEverything is clean and settled, but the deletion is not yet old enough to release the tenant's token for reuse.
NONENothing is outstanding.

ScopeAnchorKind​

enum

The kind of thing a scope anchor names.

ValueDescription
CUSTOMERA customer: the anchor covers the devices assigned to that customer.
GROUPAn entity group: the anchor covers the devices in the group while it is an access scope (at its active version), so a device moved into or out of the group is seen or not without the member being edited. A group that is not an access scope covers nothing.