Access

Manage scopes, OAuth2 clients, end-users, and active sessions for your workspace.

The Access tab is where you configure IoTMan's authorization layer: define the permissions (scopes) your workspace uses, and manage the principals — OAuth2 clients and end-users — that can access protected resources.

For a conceptual overview of how these pieces fit together, see the Authorization guide.

Scopes

A scope is a named permission string defined by your workspace. Scopes are the unit of access control — they appear in tokens and are checked by resource servers before serving protected content.

Use the namespace:action convention to keep scope names clear and consistent (e.g. sensor:read, video:gold, admin:write).

The workspace UUID is also shown in this section. External resource servers need it to validate the aud claim on incoming tokens.

Creating a scope

1. Click + New scope.
2. Enter a name and an optional description.
3. Click Save.

Requires Admin role.

Deleting a scope

Click the delete button next to a scope.

Requires Admin role.

End-users

End-users are people who access your protected resources but are not workspace members. They cannot manage the workspace — they only authenticate to receive tokens scoped to the resources you grant them.

Each end-user is invited by email and granted one or more scopes. When they authenticate, their token carries exactly the scopes you assigned. Scope changes take effect on the next token refresh.

Inviting an end-user

1. Click + Invite end-user.
2. Enter the user's email.
3. Select one or more scopes to grant.
4. Click Invite. The user receives a magic link to authenticate.

Requires Admin role.

Adding scopes to an existing end-user

Click + scope on an end-user row to grant an additional scope without re-inviting.

Requires Admin role.

Revoking a scope

Click × on a scope badge in the end-user row to revoke that specific scope. Active tokens remain valid until they expire — for sensitive resources, keep token expiry short.

Requires Admin role.

Granting internal-API (iotman:) scopes

In addition to workspace custom scopes, an end-user can be granted scopes from IoTMan's fixed internal-API catalogue (names starting with iotman:, e.g. iotman:endpoints:create). These let a PKCE token call the workspace management API directly — useful for MCP servers and third-party tools that manage a workspace on the user's behalf.

The End-users table has two scope columns per row: Workspace scopes (admin-defined) and Internal API (iotman:) (the fixed catalogue, visually distinguished with a blue tint). Use + scope in either column to add a grant to an existing row; use + Invite end-user to create a new row with both kinds of scope selected at once.

The invite dialog's Internal API scopes (iotman:) section is collapsed by default — expand it to see the full catalogue grouped by resource (workspace, members, endpoints, mqtt-configs, …). See the Authorization guide for what each scope controls.

Above the catalogue, one-click presets bundle common scope sets. Clicking a preset toggles every scope in the bundle on (or off, if already all selected), so you can pick a starting point and then fine-tune with the checkboxes below. Presets are a UI convenience — the backend stores the individual scopes, so changing a preset later does not retroactively affect existing grants. Presets are monotonic: each level is a strict superset of the previous.

• Read-only — every :read scope. Safe for monitoring, dashboards, and AI assistants that should only observe state.
• Operator — read plus create/update/activate. Excludes deletes, revokes, removals, and secret rotations. Suitable for operational tooling that configures the workspace without destructive authority.
• Full access — every iotman: scope, including deletes and workspace deletion. Useful for bootstrapping an app end-to-end; narrow to a smaller preset once setup is done.

To prevent privilege escalation, the admin issuing the grant must themselves hold the scope being granted — the backend rejects grants outside the caller's own scope set.

Requires Admin role.

OAuth2 clients

An OAuth2 client represents an application or device that interacts with your workspace. IoTMan supports three client types:

Creating a client

1. Click + New client.
2. Enter a name and select the client type.
3. For Authorization Code flows, enter the redirect URI.
4. Click Create. If the type generates a secret, it is shown once — copy it immediately.

Requires Admin role.

Scopes for Client Credentials clients

A Client Credentials client can request two kinds of scopes, both gated by per-client allow-lists:

• Workspace custom scopes (e.g. sensor:read) — only the scopes the admin explicitly grants to this client. Workspace scopes are defined workspace-wide (under Scopes above), but access to each is per-client.
• Internal-API scopes (e.g. iotman:endpoints:create) — only the iotman: scopes the admin explicitly grants to this client.

Requesting an ungranted scope returns invalid_scope. A new client with no grants therefore issues tokens with no scopes.

To manage grants, click Scopes on a Client Credentials row. An inline panel opens with two sections:

• Workspace scopes — badges for granted scopes with an inline revoke (×), and a + scope picker populated from the workspace scope registry.
• Internal API scopes — preset chips (Read-only / Operator / Full access), granted badges with revoke, and a + scope picker for individual iotman: additions.

Grants take effect on the next token issued or refreshed — active access tokens keep whatever scope set they were minted with until they expire. To prevent privilege escalation on iotman: scopes, the admin granting must themselves hold the scope.

Include a scope parameter at token request time with a space-separated list. If no scope is provided, the token carries the full allow-list union (workspace scopes granted to the client + iotman: scopes granted to the client).

Deleting a client

Click the delete button. All active tokens issued to this client are revoked immediately.

Requires Admin role.

End-user metadata

Each end-user can have arbitrary metadata attached by workspace admins or external workers. Metadata is stored as key-value pairs where values are any valid JSON.

The reserved key ingest_context is stamped onto sensor datapoints at the moment an end-user submits data via a PKCE-authenticated endpoint. This allows you to attach context — such as channel assignments or tier information — that travels with the data permanently, independent of future metadata changes.

{
  "ingest_context": { "channels": ["temperature"], "tier": "gold" }
}

Metadata is managed via the API:

PUT /api/workspaces/{ws}/end-users/{email}/metadata/ingest_context
Authorization: Bearer <admin-token>
Content-Type: application/json

{ "value": { "channels": ["temperature"], "tier": "gold" } }

End-users can retrieve their own metadata via the UserInfo endpoint using their access token.

Requires Admin role.

OAuth2 client metadata

OAuth2 clients (devices and M2M services) can also have metadata attached. Unlike end-user metadata, client metadata is not embedded in datapoints — the oauth2_client_id recorded on each datapoint allows joining against client metadata at query time.

Client metadata is exposed to resource servers via the management API:

PUT /api/workspaces/{ws}/clients/{clientId}/metadata/{key}
Authorization: Bearer <admin-token>
Content-Type: application/json

{ "value": <any JSON> }

Requires Admin role.

Active sessions

Lists all active refresh tokens issued for this workspace. Each row shows the principal (end-user email or client name), the granted scopes, and when the session was created.

Click Revoke on any row to invalidate that session immediately. M2M clients using Client Credentials re-authenticate automatically when their access token expires and do not appear here.

Requires Editor or Admin role.