GraphQL reference: user-management

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/graphql
Auth plane	tenant — The ordinary application plane. Obtain a tenant access token by calling login then selectTenant on user-management, and authorize each call with the capability it names (for example device:write).
Authorize with	tenant access token
Schema file	/schema/user-management.graphql
Described	101 of 101 elements
Note	login and refresh take no token — this is where a tenant access token comes from. Every other field on this schema requires one.

Queries

functionalAreas · identityMemberships · me · ping · tenant · tenantGovernance · tenantTokens · tokenMasks

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: an area that is enabled but down still appears. Requires only a signed-in caller.

Returns [String!]!

identityMemberships

The identity's tenant memberships as of now, with its roles in each, including any that are disabled or in a tenant that is disabled or being deleted; selectTenant refuses those. It takes the identity token returned by login, so it works before any tenant is selected and needs no Authorization header; use it to refresh a tenant picker after memberships change without logging in again. Fails with "invalid or expired token" if the identity token is expired, malformed, or from a session that has since ended (for example after a password reset or the account being disabled).

Returns [Membership!]!

Argument	Type	Description
identityToken	String!	The identity token from login.

me

The user the access token belongs to. Fails with an authentication error if the request carries no valid access token.

Returns CurrentIdentity!

ping

Liveness check. Always returns the string "pong". Needs no token.

Returns String!

tenant

The tenant the caller is currently acting within, as named by their access token. Fails with an authentication error if the request carries no tenant access token. Needs no authority beyond being signed in to the tenant.

Returns Tenant!

tenantGovernance

The limits that apply to the tenant of the current request, for the services that enforce them. The tenant comes from the access token, or from the tenant a service names when it calls with a service token. Fails if that tenant does not exist. Requires tenant:read, an instance-level authority that tenant users do not hold.

Returns TenantGovernance!

tenantTokens

The token of every tenant on the instance. Returns tokens only, not tenant records. Requires tenant:read, which only an instance-level caller holds, so a tenant user, including one with every tenant authority, cannot list tenants.

Returns [String!]!

tokenMasks

The entity token masks as a JSON object serialized to a string: it maps an entity type (or "default") to the mask template used to generate tokens for new entities of that type. A template is literal text plus the placeholders {slug}, {uuid}, {alphanumeric-N} and {numeric-N}. Masks apply to the create forms in the console; the server accepts any token that satisfies the general token format. Requires only a signed-in caller. The same masks are served on the settings API.

Returns String!

Mutations

login · logout · refresh · selectTenant · setTenantBasemap · setTenantBranding · setTenantLocale · setTenantLogo · updateProfile

login

Signs in with an email address and password. Returns an identity token and the tenants the identity may enter; call selectTenant next to obtain a tenant-scoped session. Needs no token. Fails with "invalid credentials" for an unknown email, a wrong password or a disabled account, without saying which. Repeated failures for one email are slowed down, and a request that is throttled or exceeds its allowance of password checks is refused without checking the password.

Returns IdentityAuth!

Argument	Type	Description
email	String!	Email address of the account. Case and surrounding whitespace are ignored.
password	String!	The account's password.

logout

Signs out: ends the sign-in the token belongs to, and from that moment refuses its exchanges. Refresh tokens minted from this sign-in, in any tenant, no longer refresh; its identity token can no longer select a tenant; and OAuth grants authorized during this sign-in no longer refresh. The MCP authorization page signs in on its own, so a grant made there is not ended by signing out of the console: it ends when that sign-in runs out (7 days by default). Access tokens and identity tokens already issued, including on the admin API, are not recalled and stay valid until they expire, at most 15 minutes by default. Other sign-ins of the same account, on other devices or browsers, are not affected; to end all of them, reset the password or disable the account. Needs no Authorization header. Safe to repeat, and a token that has expired still ends its sign-in. Fails with "invalid or expired token" for a token this instance did not sign or that names no sign-in, and with a retryable error, leaving the sign-in open, if the sign-out could not be recorded.

Returns Boolean!

Argument	Type	Description
token	String!	A refresh token from selectTenant or refresh, or the identity token from login.

refresh

Exchanges a refresh token for a new access and refresh pair, and consumes the refresh token: each one can be used once. The roles and authorities in the new tokens are read afresh, so a change to the user's role or membership applies from the next refresh. Needs no Authorization header. Fails with "invalid or expired token" if the refresh token is expired, already used, or belongs to a session that has ended or a membership or tenant that is no longer allowed in. If the failure is temporary the error says the session could not be refreshed right now and the same refresh token remains usable.

Returns AuthToken!

Argument	Type	Description
refreshToken	String!	The refresh token from selectTenant or an earlier refresh.

selectTenant

Exchanges an identity token for a session in one tenant. The identity must have an enabled membership in an enabled tenant; a superuser may enter any tenant. Needs no Authorization header, since the identity token is the argument. Fails with "invalid or expired token" if the identity token is expired or from a session that has ended, and with "invalid credentials" if the identity may not enter that tenant.

Returns AuthToken!

Argument	Type	Description
identityToken	String!	The identity token returned by login.
tenant	String!	Token of the tenant to enter.

setTenantBasemap

Sets the map basemap of the caller's own tenant and returns the tenant with its resulting basemap. It replaces the whole basemap: any field not sent, or sent as null or a blank string, is cleared and falls back to the instance default. An invalid value rejects the whole request. Requires basemap:write, which is separate from branding:write because the tile URL may embed the tenant's own provider key.

Returns Tenant!

Argument	Type	Description
input	TenantBasemapInput!	The basemap to apply; replaces the tenant's current basemap.

setTenantBranding

Sets the white-label theme of the caller's own tenant and returns the tenant with its resulting branding. It replaces the whole theme: any field not sent, or sent as null, is cleared and falls back to the instance default. Colors must be #rrggbb, the title at most 64 characters, and the logo height from 16 to 200 pixels; an invalid value rejects the whole request. It does not touch the logo; use setTenantLogo. Requires branding:write.

Returns Tenant!

Argument	Type	Description
input	TenantBrandingInput!	The theme to apply; replaces the tenant's current theme.

setTenantLocale

Sets the default console language of the caller's own tenant and returns the tenant. Null or a blank string clears it, so the tenant falls back to the instance default. The value must be a BCP-47 language tag of at most 35 characters in the form en, es-MX, zh-Hans or zh-Hans-CN (a two- or three-letter language, an optional four-letter script, an optional two-letter or three-digit region); its case is normalized. A well-formed tag the console has no translation for is stored and takes effect once the console supports it. Requires locale:write.

Returns Tenant!

Argument	Type	Description
locale	String	The language tag, such as "en" or "pt-BR". Null clears it.

setTenantLogo

Sets the logo of the caller's own tenant to an image URL or an inline image, or clears it, and returns the tenant. The logo must be an https URL of at most 2048 characters, or a base64 data: URI of a PNG, JPEG or WebP image of at most 256 KiB once decoded; SVG is accepted only as an https URL. Null or a blank string clears the logo. Uploading an image file is done with a separate HTTP upload endpoint rather than this mutation, and setting or clearing the logo here discards any previously uploaded image. Requires branding:write.

Returns Tenant!

Argument	Type	Description
logo	String	The logo as an https URL or an inline image data URI. Null clears it.

updateProfile

Changes the signed-in user's own first and last name and returns the updated user. The email cannot be changed here. Fields left out of the request keep their stored value. Requires only a signed-in caller.

Returns CurrentIdentity!

Argument	Type	Description
request	ProfileUpdateRequest!	The name changes to apply.

Objects

AuthToken · CurrentIdentity · IdentityAuth · Membership · Tenant · TenantBasemap · TenantBranding · TenantGovernance

AuthToken

object

A tenant-scoped session: a short-lived access token paired with a longer-lived refresh token. Returned by selectTenant and refresh.

Field	Type	Description
accessToken	String!	Signed JWT that authorizes tenant-scoped API requests; send it as Authorization: Bearer <token>. Valid until expiresAt.
expiresAt	String!	When the access token expires, as an RFC 3339 timestamp in UTC. The refresh token's own, longer expiry is not reported. The lifetimes are operator-configured; the defaults are 15 minutes for the access token and 7 days for the refresh token.
refreshToken	String!	Signed JWT whose only use is to obtain a new pair through the refresh mutation. It is single-use: refreshing consumes it and returns a new one.

CurrentIdentity

object

The signed-in user, as shown in the console.

Field	Type	Description
email	String!	The user's email address, which is their sign-in name and cannot be changed.
firstName	String	The user's first name. Null when none has been set.
lastName	String	The user's last name. Null when none has been set.

IdentityAuth

object

The result of a successful email and password login: an identity token that is not yet tied to any tenant, and the identity's memberships. Pass the identity token and a chosen tenant to selectTenant to obtain a tenant-scoped AuthToken.

Field	Type	Description
expiresAt	String!	When the identity token expires, as an RFC 3339 timestamp in UTC. It lives as long as a tenant access token (15 minutes by default, operator-configured).
identityToken	String!	Signed JWT proving who the caller is, valid across the instance rather than within one tenant. It is accepted by selectTenant, identityMemberships and the instance-level administration endpoints, and is not accepted as a tenant access token.
memberships	[Membership!]!	The identity's tenant memberships as of login, including any that are disabled or in a tenant that is disabled or being deleted; selectTenant refuses those. Call identityMemberships to re-read them later without logging in again.
superuser	Boolean!	True when the identity holds the superuser system role, which may enter any tenant with full authority whether or not it has a membership there.

Membership

object

A tenant an identity belongs to, with the roles the identity holds in it.

Field	Type	Description
roles	[String!]!	Tokens of the roles this identity holds in the tenant. Empty if it holds none.
tenant	String!	Token of the tenant, as accepted by selectTenant.

Tenant

object

The tenant the caller is acting within, as seen by that tenant's own members. It carries the settings that shape the console: white-label branding, the map basemap and the default language.

Field	Type	Description
basemap	TenantBasemap!	The map basemap in effect for this tenant: its own overrides laid over the instance-wide default. Always present; a field is null where neither level sets it, and maps with no tile source draw positions on a plain panel. Readable by any member of the tenant.
basemapOverride	TenantBasemap!	Only the basemap this tenant has set itself, with no instance default folded in: a null field means the tenant inherits it. Use it to show which values are overridden when editing; use basemap to draw maps. Readable by any member of the tenant.
branding	TenantBranding!	The white-labeling in effect for this tenant: the tenant's own overrides laid over the instance-wide default, field by field, with the tenant's value winning. Always present; a field is null when neither level sets it, and the console then keeps its built-in look for that aspect. Readable by any member of the tenant.
brandingOverride	TenantBranding!	Only the branding this tenant has set itself, with no instance default folded in: a null field means the tenant inherits that aspect. Use it to show which values are overridden when editing; use branding to apply the look. Readable by any member of the tenant.
description	String	Free-text description of the tenant. Null when none has been set.
locale	String	The default language of the console for this tenant, as a BCP-47 language tag such as "en", "es" or "pt-BR": the tenant's own setting if it has one, otherwise the instance default. Null when neither is set. It applies only to members who have not chosen a language themselves, and only when the console ships that language. Readable by any member of the tenant.
localeOverride	String	Only the default language this tenant has set itself, with no instance default folded in: null means the tenant inherits it. Use it to show whether the value is overridden when editing; use locale for the value in effect.
name	String	Human-readable name of the tenant. Null when none has been set.
token	String!	Unique identifier of the tenant on this instance.

TenantBasemap

object

The map tile source a tenant's maps draw on, plus the view they open at when there is nothing to fit to. A null field is unset.

Field	Type	Description
attribution	String	The credit line the tile provider requires, shown on the map. Plain text, in which links may be written as <a href="https://...">text</a>. Always set together with tileUrl: a tenant that sets its own tileUrl does not inherit the instance default's credit line.
centerLat	Float	Latitude in degrees, from -90 to 90, of the point maps open centered on when they have nothing of their own to fit to. Set together with centerLon.
centerLon	Float	Longitude in degrees, from -180 to 180, of the point maps open centered on when they have nothing of their own to fit to. Set together with centerLat.
tileUrl	String	URL template of the raster tiles, over https, in which {z}, {x} and {y} (or {bbox-epsg-3857}, or {quadkey}) stand for the tile being requested.
zoom	Float	Zoom level, from 0 (whole world) to 24, that maps open at when they have nothing of their own to fit to.

TenantBranding

object

White-labeling applied to the console. A null field means the console keeps its built-in look for that aspect.

Field	Type	Description
accent	String	Accent color as a hex string, #rrggbb.
background	String	Page background color as a hex string, #rrggbb.
foreground	String	Text color as a hex string, #rrggbb.
logo	String	The logo, in a form you can put straight into an image tag: an https URL, a base64 data: URI of a PNG, JPEG or WebP image, or, for an uploaded logo, a path on this API that you fetch with your access token.
logoMaxHeight	Int	Maximum height, in pixels, at which the logo is drawn, from 16 to 200.
primary	String	Primary brand color as a hex string, #rrggbb.
title	String	Product name shown in the browser tab and the console, at most 64 characters.
updatedAt	String	A version stamp, as an RFC 3339 timestamp, for caching: it changes whenever the branding may have changed. On branding it is the later of the tenant's last modification and the instance default's; on brandingOverride it is the tenant's last modification, which any change to the tenant moves, not only a branding change. Null if never modified.

TenantGovernance

object

The limits that apply to one tenant, resolved for the services that enforce them: each value is the tenant's own setting if it has one, otherwise the setting of the tenant's tier. A null limit means neither sets it, and the enforcing service then applies its platform default; null never means unlimited. Which of the two supplied a value is not reported.

Field	Type	Description
aiExternalEnabled	Boolean!	Whether the tenant has agreed to have its data sent to an external AI model provider. False unless the tenant has explicitly opted in; there is no inherited value, and a tenant that never opted in reads as false.
aiInferenceBurst	Int	How many AI inference requests the tenant may make in a burst above the sustained rate before being throttled.
aiInferenceRequestsPerMinute	Float	Sustained rate at which the tenant may make AI inference requests, in requests per minute.
geoFenceCeiling	Int	The most geofences the tenant may have at one time. When null, the platform default applies.
geoFencePositionBudget	Int	The most positions (vertices) the tenant's geofences may have in total, summed across every fence. A limit on the combined size of the whole set, independent of geoFencePositionCeiling and geoFenceCeiling. When null, the platform default applies.
geoFencePositionCeiling	Int	The most positions (vertices) one geofence may have, counted across all of its rings. A limit on the size of a single fence. When null, the platform default applies.
heldCommandCeiling	Int	The most commands the tenant may have waiting on a device that is known to be offline, in the held state. Beyond it, new commands for absent devices are refused. When null, the command service applies its configured default; there is no unlimited value.
ingestBurst	Int	How many readings the tenant may submit in a burst above the sustained ingest rate before being throttled.
ingestReadingsPerSecond	Float	The tenant's effective sustained ingest ceiling, in readings per second: its own override, else its tier's. A reading is one stored value: one measurement value, one location or one alert. Null means neither declares one and the platform default applies — never unlimited.
outboundBurst	Int	How many outbound calls the tenant may make in a burst above the sustained outbound rate before being throttled.
outboundCallsPerSecond	Float	The tenant's effective sustained outbound ceiling, in connector calls dispatched per second: its own override, else its tier's. Null means neither declares one and the platform default applies — never unlimited.
purgeState	String!	Where the tenant is in its deletion lifecycle: active for a normal tenant, or purging once the tenant has been deleted and its data is being erased. Never null.
shedPriority	Int	How strongly the tenant's traffic is protected when the platform is overloaded and has to refuse some ingest: a whole number from 1 to 100, higher meaning more protected. 80 to 100 is never refused, 50 to 79 only under the heaviest load, 20 to 49 under heavy load, and 1 to 19 first. When null, the platform treats the tenant as priority 30.
tierToken	String!	Token of the tier (the operator-defined packaging level) the tenant belongs to. Every tenant has exactly one.

Input types

ProfileUpdateRequest · TenantBasemapInput · TenantBrandingInput

ProfileUpdateRequest

input

Changes to the signed-in user's own display name. The user is identified by the request's access token, so only your own profile can be edited. For each field, leaving it out keeps the stored name, a value sets it, and null or an empty string clears it.

Input field	Type	Description
firstName	String	New first name. Omit to keep it, send null or an empty string to clear it.
lastName	String	New last name. Omit to keep it, send null or an empty string to clear it.

TenantBasemapInput

input

A basemap for setTenantBasemap. Every field is optional and the input replaces the tenant's whole basemap: a field left out or sent as null (or as a blank string) is cleared, so that aspect falls back to the instance default.

Input field	Type	Description
attribution	String	Credit line for the tiles, at most 512 characters. The only markup allowed is links written exactly as <a href="https://...">text</a>. Required when tileUrl is set, and rejected without it.
centerLat	Float	Latitude in degrees, from -90 to 90. Must be sent together with centerLon.
centerLon	Float	Longitude in degrees, from -180 to 180. Must be sent together with centerLat.
tileUrl	String	Raster tile URL template: an https URL of at most 2048 characters containing {z}, {x} and {y}, or {bbox-epsg-3857}, or {quadkey}. {prefix} and {ratio} are also substituted; any other placeholder is rejected. Requires attribution.
zoom	Float	Zoom level, from 0 to 24.

TenantBrandingInput

input

A tenant's white-labeling theme for setTenantBranding. It replaces the whole theme: a field left out or sent as null is cleared, so that aspect falls back to the instance default. The logo is not part of it; see setTenantLogo.

Input field	Type	Description
accent	String	Accent color as a hex string, #rrggbb.
background	String	Page background color as a hex string, #rrggbb.
foreground	String	Text color as a hex string, #rrggbb.
logoMaxHeight	Int	Maximum height in pixels at which the logo is drawn; from 16 to 200.
primary	String	Primary brand color as a hex string, #rrggbb.
title	String	Product name shown in the browser tab and the console, at most 64 characters.