Skip to main content
MoleSignal is multi-tenant. Every stream, dashboard, alert, and saved view belongs to an organization, and what each person can do inside an org is governed by their role. A single user can belong to several orgs with a different role in each.

​
Organizations

The first user to sign up creates an org and becomes its Owner. From there you can create more orgs, switch between them, and manage members.
ActionEndpointWho
List your orgsGET /api/v1/orgsAny member
Create an orgPOST /api/v1/orgsOrg admin
Rename an orgPATCH /api/v1/orgs/{id}Org admin
Switch active orgPOST /api/v1/orgs/{id}/selectMember
Add / change a memberPOST /api/v1/orgs/{id}/membersOrg admin
Remove a memberDELETE /api/v1/orgs/{id}/members/{user_id}Org admin
Delete an orgDELETE /api/v1/orgs/{id}Org admin
Switching orgs issues a new JWT carrying your role for that org. You can’t delete the org you’re currently in, and every user must keep at least one org.

​
Users

You add people two ways: an admin invites them, or they sign up themselves (when self-service signup is enabled for the instance).
  • Invitations — the admin chooses the email and role; the invitee joins on first login.
  • Self-service signup — controlled by two instance settings: whether signup is open at all, and whether new accounts need approval. When approval is required, a new account is pending until an Owner or Admin approves it.
Admins can list, approve, disable, and delete users. A user’s email is their identity and can’t be changed after the account is created.

​
Roles & permissions

Four built-in roles cover the common cases:
RoleWhat it can do
OwnerEverything, including organization administration. Assigned to the org creator.
AdminEverything, including organization administration and audit access.
EditorRead and write data — streams, dashboards, alerts, schedules, saved views — but not org administration or audit.
ViewerRead-only across data, plus web search and correlation.
Need something more specific? Define custom roles scoped to your org with their own permission set. Built-in roles are read-only.
ActionEndpoint
List rolesGET /api/v1/roles
Create a custom rolePOST /api/v1/roles
Update a custom rolePATCH /api/v1/roles/{id}
Delete a custom roleDELETE /api/v1/roles/{id}

​
Teams

Group members into teams so you can target them as a unit — for example, as the recipients of an alert escalation. Manage teams under settings, or over the API: 
curl -X POST http://localhost:5080/api/v1/teams \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{"name":"on-call","member_ids":["usr_abc","usr_def"]}'
Every member of a team must belong to the same org.

​
Invitations

Invite someone by email and assign their role up front: 
curl -X POST http://localhost:5080/api/v1/invitations \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{"email":"[email protected]","role":"editor"}'
You can resend (POST /api/v1/invitations/{id}/resend) or revoke (POST /api/v1/invitations/{id}/revoke) a pending invitation. Invited addresses must pass the org’s email-domain allowlist.

​
Email-domain allowlist

Restrict who can join an org by allowing specific email domains. An empty list means no restriction. 
curl -X POST http://localhost:5080/api/v1/orgs/email-domains \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{"domain":"example.com"}'
Matching includes subdomains — [email protected] is allowed by example.com. Remove a domain with DELETE /api/v1/orgs/email-domains/{domain}. The allowlist is enforced on both invitations and self-service / SSO sign-up.

​
Service accounts (API tokens)

For agents, CI, and data sources that can’t log in interactively, issue a long-lived API token. Tokens are prefixed ms_ and carry their own role. 
curl -X POST http://localhost:5080/api/v1/auth/tokens \
  -H "authorization: Bearer $MS_JWT" \
  -H 'content-type: application/json' \
  -d '{"name":"otel-collector","role":"editor","expires_in_days":365}'
FieldNotes
roleDefaults to your own role; can’t exceed it.
expires_in_daysOptional. Omit for a non-expiring token.
The token’s secret is shown once, at creation. Store it securely — you can’t retrieve it later, only revoke it (DELETE /api/v1/auth/tokens/{id}).
Use a token exactly like a login JWT — Authorization: Bearer ms_…. For a quick start, every user has a reusable default ingest token at GET /api/v1/auth/tokens/default.

​
Single sign-on (SSO)

Connect an external identity provider so people sign in with your IdP. Both OIDC and SAML 2.0 (SP-initiated) are supported. Providers are configured per org and stored in the database — no restart needed.
ActionEndpoint
List / create providersGET / POST /api/v1/sso/providers
Update / delete a providerPUT / DELETE /api/v1/sso/providers/{id}
Enable / disable a providerPOST /api/v1/sso/providers/{id}/enable · /disable
For OIDC, supply a discovery URL (or explicit authorize/token/JWKS endpoints), client credentials, and scopes. Map IdP groups to MoleSignal roles with a group → role table and a default role for unmatched users. The login flow runs through GET /api/v1/auth/sso/login and the provider callback; new users are auto-provisioned into the provider’s org with their mapped role.
SSO requires a license with the sso feature. SAML assertions are verified with real XMLDSig — enveloped signature, RSA-SHA256, and the embedded certificate is checked against the configured IdP cert. Verification targets the deterministic output of mainstream IdPs (Azure AD, Okta, Keycloak, ADFS); it does not implement exclusive XML canonicalization, so a non-canonical response is rejected.

Authentication API

Sign in, issue and revoke tokens, and rotate signing secrets over the HTTP API.