GraphQL reference: user-management-admin

Generated from the schema this service serves, so it cannot fall behind it. The same schema is published as a file for tools and agents.

Endpoint	https://<your-host>/api/user-management/admin/graphql
Auth plane	identity — 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.
Authorize with	identity token
Schema file	/schema/user-management-admin.graphql
Described	340 of 340 elements

Queries

auditEvents · authorities · deadLetter · deadLetters · functionalAreas · governanceDimensions · identities · oauthClients · ping · roles · 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!

Argument	Type	Description
criteria	AdminAuditEventSearchCriteria!	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!]!

Argument	Type	Description
scope	String	system 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

Argument	Type	Description
id	ID!	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!

Argument	Type	Description
criteria	DeadLetterSearchCriteria!	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!]!

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!]!

Argument	Type	Description
scope	String	system or tenant. Omit it to list roles of both scopes.

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

Argument	Type	Description
epoch	String	The 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.
token	String!	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!

Argument	Type	Description
criteria	TenantDeletionSearchCriteria!	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

addMembership · createIdentity · createOauthClient · createRole · createTenant · createTenantTier · deleteIdentity · deleteOauthClient · deleteRole · deleteTenant · deleteTenantTier · removeMembership · reorderTenantTiers · rotateOauthClientSecret · setIdentityEnabled · setMembershipEnabled · setMembershipRoles · setOauthClientEnabled · setPassword · setSystemRoles · setTenantEnabled · updateOauthClient · updateRole · updateTenant · updateTenantTier

addMembership

Adds an identity to a tenant with the given tenant roles and returns the identity. The membership starts enabled. Fails if the identity or tenant does not exist, if the tenant is being deleted, if a role does not exist with tenant scope, or if the identity is already a member of the tenant (error code CONFLICT). Requires user:write.

Returns AdminIdentity!

Argument	Type	Description
email	String!	Email of the identity.
roleTokens	[String!]!	Tokens of the tenant roles to grant in the tenant.
tenant	String!	Token of the tenant.

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.

Returns AdminIdentity!

Argument	Type	Description
request	AdminIdentityCreateRequest!	The identity 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!

Argument	Type	Description
request	AdminOAuthClientCreateRequest!	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.

Returns AdminRole!

Argument	Type	Description
request	AdminRoleCreateRequest!	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!

Argument	Type	Description
request	AdminTenantCreateRequest!	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!

Argument	Type	Description
request	AdminTenantTierCreateRequest!	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.

Returns Boolean!

Argument	Type	Description
email	String!	Email of the identity.

deleteOauthClient

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

Returns Boolean!

Argument	Type	Description
clientId	String!	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.

Returns Boolean!

Argument	Type	Description
scope	String!	system or tenant: the scope of the role to delete.
token	String!	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!

Argument	Type	Description
token	String!	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!

Argument	Type	Description
token	String!	Token of the tier to delete.

removeMembership

Removes an identity's membership in a tenant and returns the identity. Fails if the identity has no membership in the tenant. Requires user:write.

Returns AdminIdentity!

Argument	Type	Description
email	String!	Email of the identity.
tenant	String!	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!]!

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

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!

Argument	Type	Description
clientId	String!	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.

Returns AdminIdentity!

Argument	Type	Description
email	String!	Email of the identity.
enabled	Boolean!	True to enable, false to disable.

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. Fails if the identity has no membership in the tenant. Requires user:write.

Returns AdminIdentity!

Argument	Type	Description
email	String!	Email of the identity.
enabled	Boolean!	True to enable, false to disable.
tenant	String!	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 does not exist with tenant scope. Already-issued access tokens keep their old authorities until they expire; a refresh picks up the change. Requires user:write.

Returns AdminIdentity!

Argument	Type	Description
email	String!	Email of the identity.
roleTokens	[String!]!	Tokens of the tenant roles the identity should hold in the tenant.
tenant	String!	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!

Argument	Type	Description
clientId	String!	The clientId of the client.
enabled	Boolean!	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.

Returns AdminIdentity!

Argument	Type	Description
email	String!	Email of the identity.
password	String!	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.

Returns AdminIdentity!

Argument	Type	Description
email	String!	Email of the identity.
roleTokens	[String!]!	Tokens of the system roles the identity should hold.

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!

Argument	Type	Description
enabled	Boolean!	True to enable, false to disable.
token	String!	Token of the tenant.

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!

Argument	Type	Description
clientId	String!	The clientId of the client to update.
request	AdminOAuthClientUpdateRequest!	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.

Returns AdminRole!

Argument	Type	Description
request	AdminRoleUpdateRequest!	The changes to apply.
scope	String!	system or tenant: the scope of the role to update.
token	String!	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!

Argument	Type	Description
request	AdminTenantUpdateRequest!	The changes to apply.
token	String!	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!

Argument	Type	Description
request	AdminTenantTierUpdateRequest!	The changes to apply.
token	String!	Token of the tier to update.

Objects

AdminAuditEvent · AdminAuditEventSearchResults · AdminBurstSetting · AdminGovernanceDimension · AdminIdentity · AdminMembership · AdminOAuthClient · AdminOAuthClientSecret · AdminRateSetting · AdminRole · AdminTenant · AdminTenantSetting · AdminTenantTier · DeadLetter · DeadLetterSearchResults · SearchResultsPagination · 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.

Field	Type	Description
actor	String!	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.
category	String!	auth for a sign-in or token refresh, or mutation for a change to stored data.
entityLabel	String	A 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.
entityPk	String	Identifier of the changed record, when a single record was changed. Null otherwise.
id	ID!	Server-assigned identifier of the entry.
occurredTime	String!	When the event happened, as an RFC 3339 timestamp.
operation	String!	What happened: login, login_failed or refresh for an auth entry; create, update or delete for a mutation entry.
rowsAffected	Int!	How many records the change affected.
tableName	String	Qualified name of the stored collection that was changed. Null for an auth entry.
tenant	String	Token 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.

Field	Type	Description
pagination	SearchResultsPagination!	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.

Field	Type	Description
override	Int	The tenant's own override for this dimension. Null if it has none.
source	String!	Which level supplied the value: override, tier or platform-default, as for AdminRateSetting.
tier	Int	What the tenant's tier sets for this dimension. Null if the tier sets none.
value	Int	The 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.

Field	Type	Description
burstField	String!	Name of the setting that holds this dimension's burst allowance, used the same way as rateField.
label	String!	Human-readable heading for the dimension, such as "Ingest".
name	String!	Short stable identifier of the dimension, such as ingest.
rateField	String!	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.
rateUnit	String!	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.

Field	Type	Description
createdAt	String	When the identity was created, as an RFC 3339 timestamp.
email	String!	The identity's email address, stored lower-cased. It is the sign-in name and cannot be changed.
enabled	Boolean!	False when the identity is disabled and cannot sign in.
firstName	String	First name. Null when none has been set.
id	ID!	Server-assigned identifier. Address an identity by its email, not by this.
lastName	String	Last name. Null when none has been set.
memberships	[AdminMembership!]!	The tenants the identity belongs to, each with its roles there.
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.
updatedAt	String	When 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.

Field	Type	Description
enabled	Boolean!	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.
tenant	String!	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.

Field	Type	Description
clientId	String!	The client's public identifier, as presented in authorization requests. It cannot be changed.
createdAt	String	When the client was registered, as an RFC 3339 timestamp.
description	String	Free-text description. Null when none has been set.
enabled	Boolean!	False when the client is disabled; the authorization and token endpoints then reject it.
hasSecret	Boolean!	True for a confidential client, which authenticates with a secret. False for a public client, which authenticates with PKCE instead.
id	ID!	Server-assigned identifier. Address a client by its clientId, not by this.
name	String	Human-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.
updatedAt	String	When 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.

Field	Type	Description
client	AdminOAuthClient!	The registered client as it now stands.
clientSecret	String	The 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.

Field	Type	Description
override	Float	The tenant's own override for this dimension. Null if it has none.
source	String!	Which level supplied the value: override (the tenant's own setting), tier (its tier's setting) or platform-default (neither sets one).
tier	Float	What the tenant's tier sets for this dimension. Null if the tier sets none.
value	Float	The 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.

Field	Type	Description
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.
createdAt	String	When the role was created, as an RFC 3339 timestamp.
description	String	Free-text description. Null when none has been set.
id	ID!	Server-assigned identifier. Address a role by its scope and token, not by this.
name	String	Human-readable name. Null when none has been set.
scope	String!	Either system or tenant: who the role can be assigned to and which authorities it can grant.
token	String!	Identifier of the role, unique within its scope.
updatedAt	String	When 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.

Field	Type	Description
aiExternalEnabled	Boolean	Whether 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.
aiInferenceBurst	Int	The tenant's own override of its AI inference burst allowance, in requests. Null means no override.
aiInferenceRequestsPerMinute	Float	The 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.
config	String	Free-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.
createdAt	String	When the tenant was created, as an RFC 3339 timestamp.
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.
enabled	Boolean!	False when the tenant is disabled. Members cannot enter a disabled tenant, though a superuser still can.
geoFenceCeiling	Int	The tenant's own override of the most geofences it may have. Null means no override: the tier's value applies, then the platform default.
geoFencePositionBudget	Int	The 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.
geoFencePositionCeiling	Int	The 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.
heldCommandCeiling	Int	The 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.
id	ID!	Server-assigned identifier. Address a tenant by its token, not by this.
ingestBurst	Int	The tenant's own override of its ingest burst allowance, in readings. Null means no override.
ingestReadingsPerSecond	Float	This 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.
name	String	Human-readable name. Null when none has been set.
outboundBurst	Int	The tenant's own override of its outbound burst allowance, in calls. Null means no override.
outboundCallsPerSecond	Float	This 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.
purgeEpoch	String	When 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.
purgeState	String!	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.
shedPriority	Int	The 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.
tier	AdminTenantTier!	The tier the tenant is packaged at. Every tenant has exactly one.
token	String!	Unique identifier of the tenant on this instance. It cannot be changed.
updatedAt	String	When the tenant was last changed, as an RFC 3339 timestamp.

AdminTenantSetting

object

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

Field	Type	Description
burst	AdminBurstSetting!	The burst allowance.
dimension	AdminGovernanceDimension!	The dimension these limits apply to.
rate	AdminRateSetting!	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.

Field	Type	Description
color	String	Name of the color the console shows for this tier, one of those listed by tierColorPalette, or null for no color. Presentation only.
config	String	The 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.
createdAt	String	When the tier was created, as an RFC 3339 timestamp.
description	String	Free-text description of the tier. Null when none has been set.
displayOrder	Int!	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.
id	ID!	Server-assigned identifier. Address a tier by its token, not by this.
name	String	Human-readable name of the tier. Null when none has been set.
tenantCount	Int!	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.
token	String!	Unique identifier of the tier.
updatedAt	String	When 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.

Field	Type	Description
attempts	Int!	How many delivery attempts were made before giving up.
correlation	String	Identifier of the request the work belonged to, for matching against logs. Null when not recorded.
detail	String	The underlying error text. It can name destinations a tenant configured, so treat it as operator-only. Null when there is nothing to add.
id	ID!	Server-assigned identifier of the record, as accepted by the deadLetter query.
kind	String!	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.
occurredTime	String!	When the platform gave up, as an RFC 3339 timestamp.
reason	String!	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).
reference	String	Identifier of the specific thing that failed within its kind, such as a rule, alarm or command token. Null when not recorded.
sequence	String	Position 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.
source	String!	Name of the functional area that gave up.
subject	String	Where the original message was published, for locating it while the platform still retains it. Null when not recorded.
summary	String!	A fixed sentence describing the class of failure. Safe to show to anyone.
tenant	String!	Token of the tenant whose work this was.

DeadLetterSearchResults

object

One page of dead letters, newest first.

Field	Type	Description
pagination	SearchResultsPagination!	Where this page sits in the full result set.
results	[DeadLetter!]!	The records on this page, newest first.

SearchResultsPagination

object

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

Field	Type	Description
pageEnd	Int	Position of the last result on this page within the full result set (1-based, inclusive).
pageStart	Int	Position of the first result on this page within the full result set (1-based).
totalRecords	Int	Number of records matching the criteria across all pages.

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.

Field	Type	Description
awaiting	DeletionWait!	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.
completedAt	String	When every storage system had reported clean and the token was released, as an RFC 3339 timestamp. Null while the deletion is in progress.
elapsesAt	String	When 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.
epoch	String!	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.
rowsErased	Int!	Total number of records erased across all storage systems.
stores	[TenantDeletionStore!]!	One line per storage system, ordered by name.
token	String!	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.

Field	Type	Description
pagination	SearchResultsPagination!	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.

Field	Type	Description
attemptedAt	String	When this storage system was last checked, as an RFC 3339 timestamp. Null if it has not been checked yet.
cleanSince	String	When 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.
complete	Boolean!	True once this storage system has reported that it holds nothing for the tenant.
lastError	String	A 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.
note	String	A 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.
retaining	String	A 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.
rowsErased	Int!	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.
store	String!	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.

Field	Type	Description
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 · TenantDeletionSearchCriteria

AdminAuditEventSearchCriteria

input

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

Input field	Type	Description
actor	String	Only entries whose actor contains this text. The match ignores case.
category	String	Only entries of this category, auth or mutation. Exact match.
endTime	String	Only entries at or before this time, as an RFC 3339 timestamp.
operation	String	Only entries of this operation, such as login or update. Exact match.
pageNumber	Int!	Page to return, starting at 1.
pageSize	Int!	Results per page. Below 1 means the default of 100; above 1000 is capped at 1000.
startTime	String	Only entries at or after this time, as an RFC 3339 timestamp.
tenant	String	Only entries belonging to the tenant with this token. Exact match. Entries that belong to no tenant are excluded when this is set.

AdminIdentityCreateRequest

input

Fields for a new identity.

Input field	Type	Description
email	String!	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.
enabled	Boolean!	Whether the identity may sign in. Send false to create it disabled.
firstName	String	Given name, shown in the console. A blank value is stored as unset.
lastName	String	Family name, shown in the console. A blank value is stored as unset.
password	String!	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 field	Type	Description
clientId	String!	The client's public identifier: letters, digits, -, _ and ., at most 128 characters. It cannot be changed.
confidential	Boolean	True to register a confidential client, for which a secret is generated and returned once. False or omitted registers a public client that uses PKCE.
description	String	Free-text description.
name	String	Human-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 field	Type	Description
description	String	New description, or null to clear it.
name	String	New 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 field	Type	Description
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.
description	String	Free-text description.
name	String	Human-readable name.
scope	String!	system or tenant. A role's scope cannot be changed afterwards.
token	String!	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 field	Type	Description
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.
description	String	New description, or null to clear it.
name	String	New name, or null to clear it.

AdminTenantCreateRequest

input

Fields for a new tenant.

Input field	Type	Description
aiExternalEnabled	Boolean	Records the tenant's agreement to have its data sent to an external AI model provider. Omit it for not agreed.
aiInferenceBurst	Int	Override of the AI inference burst allowance, in requests. Must be positive. Omit to inherit.
aiInferenceRequestsPerMinute	Float	Override of the sustained AI inference rate in requests per minute. Must be positive. Omit to inherit.
config	String	Free-form settings as a JSON object serialized to a string. Omit it, or send an empty string or {}, for none.
geoFenceCeiling	Int	Override 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.
geoFencePositionBudget	Int	Override 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.
geoFencePositionCeiling	Int	Override 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.
heldCommandCeiling	Int	Override 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.
ingestBurst	Int	Override of the ingest burst allowance, in readings. Must be positive. Omit to inherit.
ingestReadingsPerSecond	Float	Ingest ceiling override, in readings (decoded samples) per second. Must be positive; omit it to inherit the tier's ceiling, then the platform default.
name	String	Human-readable name.
outboundBurst	Int	Override of the outbound burst allowance, in calls. Must be positive. Omit to inherit.
outboundCallsPerSecond	Float	Outbound ceiling override, in connector calls dispatched per second. Must be positive; omit it to inherit the tier's ceiling, then the platform default.
shedPriority	Int	Override 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.
tierToken	String!	Token of the tier to package the tenant at. The tier must exist.
token	String!	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 field	Type	Description
color	String	A color name from tierColorPalette. Omit it, or send null or an empty string, for no color; an unknown name rejects the request.
config	String	The 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.
description	String	Free-text description.
name	String	Human-readable name.
token	String!	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 field	Type	Description
color	String	A color name from tierColorPalette, trimmed of surrounding spaces. Null or an empty string clears it; an unknown name rejects the request.
config	String	The 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.
description	String	New description, or null to clear it.
name	String	New 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 field	Type	Description
aiExternalEnabled	Boolean	Whether the tenant has agreed to have its data sent to an external AI model provider. Null clears the record, which counts as not agreed.
aiInferenceBurst	Int	Override of the AI inference burst allowance, in requests. Must be positive.
aiInferenceRequestsPerMinute	Float	Override of the sustained AI inference rate, in requests per minute. Must be positive.
config	String	Free-form settings as a JSON object serialized to a string, replacing the current ones. Null, an empty string or {} clears them.
geoFenceCeiling	Int	Override of the most geofences the tenant may have. A positive whole number of at most 4000.
geoFencePositionBudget	Int	Override of the most positions the tenant's geofences may have in total. A positive whole number of at most 128000.
geoFencePositionCeiling	Int	Override of the most positions one geofence may have. A positive whole number of at most 1024.
heldCommandCeiling	Int	Override of how many commands may be held waiting for offline devices. A positive whole number.
ingestBurst	Int	Override of the ingest burst allowance, in readings. Must be positive. Omitted leaves it as it is; null removes it so the tenant inherits.
ingestReadingsPerSecond	Float	Ingest 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.
name	String	New name, or null to clear it.
outboundBurst	Int	Override of the outbound burst allowance, in calls. Must be positive. Omitted leaves it as it is; null removes it so the tenant inherits.
outboundCallsPerSecond	Float	Outbound 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.
shedPriority	Int	Override of the overload-protection priority, a whole number from 1 to 100.
tierToken	String	Token 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 field	Type	Description
kind	String	Only records of this kind. Exact match.
pageNumber	Int!	Page to return, starting at 1.
pageSize	Int!	Results per page. Below 1 means the default of 100; above 1000 is capped at 1000.
since	String	Only records that occurred at or after this time, as an RFC 3339 timestamp. A value that cannot be parsed is an error, not ignored.
source	String	Only records from this functional area. Exact match.
tenant	String	Only records for the tenant with this token. Exact match.
until	String	Only records that occurred at or before this time, as an RFC 3339 timestamp. A value that cannot be parsed is an error, not ignored.

TenantDeletionSearchCriteria

input

Paging and an optional completion filter for listing tenant deletions.

Input field	Type	Description
completed	Boolean	True for deletions that have finished, false for those still in progress. Omit it for both.
pageNumber	Int!	Page to return, starting at 1.
pageSize	Int!	Results per page. Below 1 means the default of 100; above 1000 is capped at 1000.

Enums

DeletionWait

DeletionWait

enum

What a tenant deletion is currently waiting on.

Value	Description
STORES	At least one storage system has not reported clean. This is the only wait that needs a person; blockedBy says which system and why.
SETTLE	Every storage system is clean but has not yet stayed clean for the required settling period.
TOKEN_HOLD	Everything is clean and settled, but the deletion is not yet old enough to release the tenant's token for reuse.
NONE	Nothing is outstanding.