Workspaces

How to create, rename, and delete workspaces in IoTMan.

A workspace is an isolated container for all your IoTMan resources: HTTP endpoints, MQTT connectors, ingested data, and OAuth clients. Every user starts with one workspace; you can create more to separate environments or projects.

Switching workspaces

Click the workspace name in the top-left of the sidebar. A dropdown lists all workspaces you belong to. Click any entry to switch.

Creating a workspace

1. Open the workspace dropdown.
2. Click + New workspace.
3. Type a name and press Enter.

The new workspace becomes active immediately.

Workspace settings

Click the gear icon (⚙) next to the workspace name to open the workspace settings panel. From here you can rename the workspace, manage members, and delete the workspace.

Renaming a workspace

1. Open workspace settings (⚙).
2. Edit the name in the field that appears.
3. Press Enter to save, or Escape to cancel.

Requires Admin role.

Deleting a workspace

1. Open workspace settings (⚙).
2. Click Delete workspace… and confirm.

Deletion is permanent and removes all resources inside the workspace: ingested data, HTTP endpoints, MQTT connectors, and OAuth clients. You cannot delete your last workspace.

Requires Admin role.

Members

The members section lists everyone with management access to the workspace and their role. Members can configure connectors, manage OAuth2 clients, and view data depending on their role.

Members are distinct from end-users, people who access your protected data endpoints or external services using IoTMan-issued tokens, but who have no workspace management role. End-users are managed in the Access tab.

Inviting a member

1. Open workspace settings (⚙).
2. Click Invite member.
3. Enter the user's email and pick a role (Viewer, Editor, or Admin).
4. Click Send invite.

An invitation email is sent with an accept link of the form https://<your-host>/invitations/accept?token=<uuid>. The token expires after 7 days. The invitee must sign in (the accept page redirects them to /login and routes them back automatically). Acceptance only succeeds when the invitee signs in with the same email the invitation was sent to.

Pending invitations appear in a table below the member list with the invitee's email, role, and the date the invitation was sent. Click × to cancel one; the recipient's link stops working immediately.

Requires Admin role.

Removing a member

Click the remove icon on a member row. The user loses access immediately.

Requires Admin role.

AsyncAPI spec

Each workspace is described by a per-workspace AsyncAPI 3.0 document that captures every ingest, stream, and webhook channel along with the schemas, tag rules, and outputs that shape them. The Workspace settings panel exposes three controls:

• Download opens asyncapi.yaml or asyncapi.json in a new tab. The document is the lossless source of truth for your workspace and is suitable for codegen or for checking into version control.
• Public access toggles workspaces.asyncapi_public. When off, the document is readable by workspace members (session cookie) or by Bearer tokens carrying the iotman:asyncapi:read scope. When on, the URL is anonymously readable.
• Import accepts a pasted YAML or JSON document. Dry-run returns the diff that would be applied; Apply commits the changes inside one transaction. Apply requires the iotman:asyncapi:write scope. Webhook secrets do not round-trip; freshly created webhooks return a new secret in the apply response, which you can copy once.

Apply requires Admin or Editor role. The Public toggle requires Admin.

Hand-editing the document

The exported document uses human-readable channel, message, and schema keys derived from each entity's name — ingest_<source-slug> for HTTP/MQTT sources, stream_<endpoint-slug> for export endpoints, webhook_<webhook-slug> for outbound webhooks, with paired source_<slug>.payload / export_<slug>.event / output_<slug>.payload entries under components.messages. The keys are advisory: the importer identifies entities by the IDs embedded in the x-iotman-* extensions (sourceId, endpointId, subscriptionId, outputId, ruleId), so you can rename a channel or message key freely without affecting the roundtrip.

To add a new source, output, tag rule, export endpoint, or webhook by hand, omit the corresponding ID field. The importer mints a fresh UUIDv7 for any x-iotman-* entry that lacks an ID and treats it as a new entity on apply. To update an existing entity, keep its ID; to delete one, omit it from the imported document (Import replaces the workspace's state with the document's, so an absent entity is a delete).

Workspace SMTP

By default iotman sends invitation emails (and, soon, end-user verification and transactional messages) through the platform SMTP server, so they originate from an @iotman.io address. Configure a workspace SMTP server to send those messages from your own domain instead.

The Workspace settings panel exposes a Workspace SMTP form with the following fields:

• Host and Port of your SMTP relay (e.g. smtp.postmarkapp.com:587).
• Username and Password issued by your provider. The password is encrypted at rest with AES-256-GCM keyed by the server's EMAIL_SMTP_ENCRYPTION_KEY and is never returned by GET. Updates that omit the password keep the stored value.
• Security mode: STARTTLS (port 587, opportunistic upgrade), TLS (port 465, implicit), or Plain (no TLS, only for local relays).
• From address and From display name that appear on outgoing mail.

Click Save to store the credentials, then Send test to route a one-off message through the new config before any production flow uses it. Click Remove workspace SMTP to delete the config; iotman falls back to the platform SMTP afterwards.

Saving, removing, and test-sending require Admin or Editor role. Reading the form requires Viewer or higher.

Why use it

The platform SMTP gets the job done in dev and for small projects, but recipients see iotman branding in the From: header. A workspace SMTP server lets you keep the user experience inside your product: emails come from your domain, deliverability ties to your domain reputation (SPF/DKIM/DMARC aligned to you, configured at your provider), and quota plus bounces stay with your account.

Email deliveries

Below the form, the Email deliveries card lists the 50 most recent attempted sends with their recipient, purpose, transport (workspace_smtp or platform_smtp), status, and any error message. Click Refresh to reload after triggering a new send. Failed rows display the SMTP error inline so you can diagnose deliverability problems without leaving the dashboard.

MCP server

Each workspace exposes a Model Context Protocol endpoint at https://iotman.io/mcp/<workspace-slug>. The slug is the same identifier used in ingest URLs and on the dashboard router (?ws=<slug>); the Workspace settings panel shows the full MCP URL with a copy button. Every iotman management API operation surfaces as an MCP tool, plus workspace_spec_get and workspace_spec_import for bulk AsyncAPI configuration, and iotman_call as a generic escape hatch for paths without a dedicated tool (data-ingest POSTs, token introspection).

Append ?mode=lean to the URL for the GET-only catalogue (about a third of the tools), useful when agent context is tight.

Authentication uses the same OAuth2 stack as the rest of iotman. Spec-compliant clients (Claude Code, MCP Inspector) probe /.well-known/oauth-protected-resource under the MCP URL, register dynamically via PKCE, and obtain an access token. Permissions match the caller's token scopes, granted from the Access tab.

Roles

Each workspace member has one of three roles: