Referencia GraphQL: user-management
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.
| Endpoint | https://<your-host>/api/user-management/graphql |
| Plano de autenticación | 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). |
| Autorización | tenant access token |
| Archivo del esquema | /schema/user-management.graphql |
| Descritos | 101 de 101 elementos |
| Nota | login and refresh take no token — this is where a tenant access token comes from. Every other field on this schema requires one. |
La referencia que sigue se genera a partir del esquema y está solo en inglés.
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. |