Organizations, users & roles¶

Tenant and child organizations¶

Your tenant (workspace) is your whole CertIntel account. Inside it, child organizations are the unit almost everything else is scoped to: monitored targets, certificates, API keys, install tokens, and DNS delegations each belong to one child organization, or - for select resources, at a tenant administrator's discretion - are left tenant-wide (visible/usable across every organization in the tenant).

A small account might run everything in a single default organization. A larger one splits by team, business unit, region, or customer, so that e.g. an organization administrator in one team can't see or touch another team's certificates and keys. A managed service provider runs one workspace with an organization per client; see MSP mode.

The organization selected in the dashboard's top bar is pre-selected in every "create" form (targets, keys, install tokens, delegations, trusted CAs), so check it before saving. Credential creation shows the affected scope before saving. An administrator confined to a child organization cannot create a workspace-wide credential or manage another organization's inventory. Tenant suspension blocks user access, machine reporting, delegated DNS updates/answers, scheduled probes, and notifications until the workspace is resumed.

Deleting an organization¶

Organizations → Edit → Delete removes an empty child organization. An organization that still owns anything - monitored targets, API keys, members, DNS delegations, internal endpoints, CT-watched domains, identity providers, AD CS templates, agents, alert destinations, trusted or ignored CAs, or ACME accounts - is refused with a message naming what blocks it, for example 'Team A' still owns resources (2 targets and 1 DNS delegation). Type PURGE Team A to force. Move or delete those resources first, or type PURGE <name> in the confirmation box to delete the organization together with everything it owns. The API returns 409 with the same list.

A session switched into a client can't delete or purge that client, with or without the typed confirmation: the page says While switched into this client you cannot delete it. Switch back to all clients first. and the API answers 403. Renaming it is still allowed.

Tenant appearance¶

On supported plans, tenant administrators can customize dashboard colors, choose a comfortable or compact layout density, and upload a logo and favicon from Tenant appearance. That is the default for everyone in the tenant; each user can pick their own light/dark mode and density under My appearance, and enrolled Windows Agents follow the tenant's button colors unless a server administrator enables Tenant override in Agent settings. See Branding & appearance. With MSP mode, a client organization can also carry its own name and logo (co-branding) next to the tenant's branding.

MSP mode¶

On plans that include MSP (the Enterprise plan; entitlement msp), a managed service provider runs its clients from one workspace: the workspace (tenant) is the MSP and each child organization is a client. There is no model that spans several tenants. MSP mode adds client co-branding, an audited switch into client and the Clients page; an organization's limit override can turn it off for one client.

Client co-branding¶

A user with workspace-wide branding.update (a tenant administrator, or a custom role granted workspace-wide) opens Organizations, then Co-branding on a client's row:

Save co-branding confirms Co-branding for '<organization>' saved. and writes organization.branding_updated to the activity log. While the dashboard shows only that organization (selected in the top bar, or after switching into it), its users see the client's name and logo beside the workspace branding. The logo is served only to signed-in users of the workspace who can reach that organization. Emails and scheduled reports for that organization read <workspace> for <client> in their header, as text only; emails carry no logo. Without the plan feature the form is not shown and a save is refused (Your plan does not include MSP co-branding.).

Switch into a client¶

On the Clients page, Switch into shows the dashboard as that client only. It is for workspace-wide accounts (tenant administrators and workspace-wide roles); others get Switching into a client is for workspace-wide accounts.

• A banner reads Viewing <client> as <user> with Return to all clients**, which also replaces the organization switcher in the top bar.
• While switched, every other organization is out of reach, also by its direct address: pages and API calls made with the dashboard session answer not found for another organization's resources.
• Users are narrowed the same way: the Users page and the user API list, open and change only the client's users, as for an administrator of that one organization. Users of other clients and users with workspace-wide authority answer not found.
• Nothing that reaches every client is created or changed while switched: a workspace-wide API key (the key form stops offering it, so a switched session creates only keys confined to that client), the tenant administrator flag or a workspace-wide role on a user, a user outside the client, an organization, a custom role (a user role or an API role), a workspace-wide identity provider, a workspace-wide trusted CA, whether the workspace trusts the platform's default CAs, or the workspace ignore list (adding or removing an entry). Those are refused with While switched into one client you cannot … Switch back to all clients first.
• The client you are switched into can't be deleted or purged from that session. Renaming it is allowed.
• The workspace settings are refused the same way: the Security page (IP allowlist, sign-in and dashboard settings, What your agents may submit, the two-factor policy, the workspace name, address and time zone, and the vanity domain), the appearance (colours, layout density, logo and favicon), and workspace-wide alert destinations, alert contacts and scheduled reports (adding, changing or deleting one). Sending a test or a report by hand stays allowed: it changes nothing. The client's own settings stay editable.
• The switch belongs to the signed-in session and ends at sign-out.
• Both directions are audited: organization.switch_into (<user> switched into the client organization <client>.) and organization.switch_out (<user> returned from the client organization <client> to all clients.).

The ordinary organization switcher in the top bar is unchanged: it narrows lists and forms but is not audited and does not block a direct address to another organization. Switching into a client is not acting as a tenant: a platform operator's time-boxed act-as session (see Delegation is bounded) is a platform-side support session, while switching into a client is a workspace user narrowing their own view.

The Clients page¶

Clients (/msp, in the Monitor section of the navigation) lists every client organization by what needs attention: Every client organization in this workspace, by what needs attention. Tiles show Clients needing attention, Expired certificates, Expiring certificates and Renewal failures (7 days). Client priorities has one row per organization:

Each number is a link to the list of what it counts, narrowed to that client. It does this through the organization switcher in the top bar, which then shows that client until you change it. The Expired certificates, Expiring certificates and Renewal failures (7 days) tiles open the same lists for every client and set the switcher back to all organizations. A zero is not a link, and neither is a number whose list your role cannot open. While you are switched into a client, the numbers open the lists directly.

A co-branded pill marks co-branded clients, and each row has Switch into (or Current client). The page needs workspace-wide reach and organizations.read; every count covers only organizations you can read. The API is GET /api/v1/msp/organizations, returning organization_id, name, co_brand_enabled, expiring, expired, renewal_failures_7d, served_mismatches, offline_agents and ct_new_name_sets per organization.

Expiry severity settings¶

On Organizations, open a child organization's Edit form. Administrators can set these Expiry severity overrides:

Above the fields the form says, in these terms, when the warning and critical windows start - The warning starts when 21 full days are left and the critical window when 7 full days are left. - when a short-lived certificate gets shorter windows, and When the agent renews a certificate by itself, you are warned only if it has not renewed 24 hours after the renewal the agent planned (at the latest when the critical window starts). That hold applies to the warning only, for a certificate whose Agent reports a planned renewal; the critical alert is never held, and once the planned renewal plus 24 hours has passed with the certificate still current, the configured warning applies. Blank fields inherit the platform's defaults. Clearing all three removes the organization override. Days must be nonnegative whole numbers. Expiry severity overrides can only be set from the dashboard; the REST API's organization update accepts the name, slug and identity-provider flag only.

These settings affect certificate severity and expiry notification evaluation. They do not choose when an Agent renews a certificate. See how lifetime scaling works and Agent renewal windows.

Built-in roles¶

A role has a kind. A user role is granted to people; an API role is given to API keys. The kind is fixed when the role is created: a user role cannot be given to a key, and an API role cannot be given to a user or to an identity-provider mapping (the API answers 422 and says why). The Roles page has a tab for each kind, User roles and API roles, with the same editor. This section and Custom roles describe user roles; the three built-in API roles, custom API roles and who may give a key a role are under API roles.

User roles are assigned per-user, either within one organization or, for a tenant administrator, across the whole tenant. The built-in roles below grant access within their assigned organization scope.

Open Access → Roles to see exactly which permissions each built-in role holds. For a colleague who should follow certificates and alerts but change nothing, grant Observer: unlike Auditor, it shows nothing about users, roles, identity providers, the activity log or workspace settings, so an organization Administrator can grant it in their organization.

A read-only role such as Observer or Viewer is not offered actions it cannot take. The Overview and the empty Certificates and Agents pages offer Get a certificate for a server only to a role that can propose a certificate (workflow_assignments.create), and Set up an agent only to a role that can show or create install tokens. With neither, the Overview says No monitoring resources are visible yet. Your role can view certificates, endpoints and agents once a workspace administrator adds them; they appear here as soon as they report. The empty Workflow Assignments, Endpoints and Certificate Transparency pages and the Trusted CAs page likewise mention proposing, adding or acknowledging only to a role that may do it. The introductions of Alert Settings, Delegated DNS-01, Scheduled Reports, ACME Accounts, AD CS Templates, CRL Distribution Points and Install Tokens describe the page to a role that cannot change it instead of telling it what to do; Alert Settings, Delegated DNS-01 and Install Tokens add that an administrator makes the changes. A page the role cannot open reads Not available (Your role does not have access to this page.) and keeps the workspace and organization in the header.

The badge in the dashboard header names your own roles (one or two, then +N; hover for the full list), including custom roles with their own names. Workspace administrators by status alone, demo accounts and API keys show a label derived from their permissions instead.

A user can hold tenant administrator authority in addition to (or instead of) an organization role - that's what lets someone manage every organization, create tenant-wide resources, and grant roles to other users. The tenant administrator status alone carries every Administrator permission in every organization, whether or not an Administrator role is also assigned: an account given only the tenant administrator flag (is_tenant_admin in the API, or by an identity provider mapping) is a complete administrator.

Adding a user¶

On Users, Invite a user is the default way to add someone: enter their email address, choose the access (an organization and its role, or Whole workspace (every organization) with a workspace-wide role; Also make workspace administrator for a tenant administrator), and click Send invitation. The user is created as invited and gets an email naming who invited them, the workspace, the access granted and a single-use link to choose their own password. The email names the inviter by display name, or by email address when they have none; a new workspace's first administrator starts without a display name (set one on Users). The link is valid for 72 hours (the deployment setting CERTINTEL_INVITE_TTL_HOURS); the user list shows until when. Following it, the user sets a password and is signed in with exactly the access granted; Last login on Users records that sign-in, as it does for every sign-in method. An invited user takes a seat of the plan's Users limit.

An invitation or password-reset link works only at the address in the email or at the account's own workspace address. Opened anywhere else - another workspace's address, for example - it reads as expired (This invitation link has expired or was already used.) and is not used up, so it still works at the right address.

A link opened in a browser that is signed in to another account - the administrator who sent it, for example - says so: This browser is signed in as …. To accept the invitation as …, sign out of that account first. Sign out and continue ends that session, as Sign out does, and then shows the invitation's password form; to stay signed in, open the link in another browser or a private window instead. A password form sent from an older tab while signed in is refused with the same explanation; the link is not used up and the session stays.

The Users list's Roles column names each role and where it applies, for example Observer · Default or Administrator · all organizations, and sorts by that text; the role filter lists the role names too.

Under Manage, an invited user offers Send invitation again (a new link; the previous one stops working) and Revoke invitation (the link stops working and the never-used account is removed, so its seat and address are free again). Set a temporary password instead creates the user with a password you give them; they must change it at first sign-in and cannot submit anything else in the dashboard until they do. A deployment that sends no email offers only the temporary password.

The invitation follows the same rules as any new user: it can carry only authority you hold where it is granted, and it cannot be sent from inside a platform operator's act-as session.

Invitations, new ones and ones sent again, are limited to 20 an hour per inviter and 50 an hour per workspace. Over a limit nothing is created or sent, and the API answers 429 with Retry-After: You have sent too many invitations (at most 20 per hour, all together): try again in N seconds. for your own limit, Too many invitations from this workspace: try again in N seconds. for the workspace's. Names and other text someone typed (the invitee's and inviter's names, the workspace, role and organization names) appear in the email on one line, without control or invisible characters, and names are shortened to 80 characters.

Who can manage whom¶

Inviting or creating a user needs users.create in each organization the new user joins, and nothing more: no users.read or users.update there. It is held by Administrators (within their organization), tenant administrators, or a custom role that holds it; the catalogue describes it as Invite or create user accounts, with roles you hold yourself, because the roles you hand out are still only roles you hold yourself in that organization. Adding a user to an organization where you lack it is refused with You can only add users to organizations where you may create users. Changing an existing user's organizations or roles needs users.update. Opening the Users page needs users.read; other roles get Your role does not have access to this page. Email addresses are unique within the tenant (A user with that email already exists in this tenant.), and only a tenant administrator can grant tenant-wide authority (Only a tenant administrator can grant tenant-wide authority.).

Users with tenant-wide authority - tenant administrators, holders of a tenant-wide (global) role, and platform administrators - can only be managed by a tenant administrator. An organization Administrator cannot see, reset the password of, disable, or change the roles of such a user, even if that user also has a membership in the administrator's organization; those users simply do not appear in that administrator's user list.

Changing another user - their password, email, two-factor sign-in, status (disable, enable), roles, or deleting them - also needs at least their authority: you must hold every permission they hold, where they hold it (their workspace-wide permissions workspace-wide, each organization's permissions in that organization). Equal authority is enough, so an organization Administrator can manage another Administrator of the same organization, and a custom role of Viewer plus users.read / users.update can manage Viewers but not Operators or Administrators. A user you can see but who holds more than you is refused with 403 and You can only change users whose permissions you hold yourself in their organization. Missing: … (or … across the whole workspace. Missing: …). A user with tenant-wide authority is changed only by a tenant administrator (Only a tenant administrator can change a user with tenant-wide authority.), and a platform administrator only by a platform administrator. Your own account is self-service and keeps its own rules below.

A role granted workspace-wide that includes users.* manages users in every organization where it holds the permission (all of them for a workspace-wide grant), bounded by the same rule; users with tenant-wide authority stay visible to tenant administrators only.

Deleting a user frees their email address: it can be given to a new user or to another user's address change at once. The deleted account keeps its history under a placeholder address (deleted-<id>@deleted.invalid), and the activity log records user.email_released naming the deleted account that held the address. A live user's address is still refused (409).

Deleting a user ends their sessions and their outstanding invitation or password reset links at once. The deleted account is erased 30 days later. Until then, a user created by an identity provider can't sign in through it again; see Deleted users.

A tenant always keeps at least one active tenant administrator. You cannot disable or demote your own account, and no surface (API, dashboard, or platform console) will disable, demote, or delete the last active tenant administrator; promote a successor first. The error reads The last active tenant administrator cannot be disabled. (or demoted / deleted). A disabled or still-invited administrator does not count as active.

Demo accounts are always treated as read-only Viewers with redacted data, whatever roles they hold.

The same rules decide who may Reset two-factor for a user (Users → Manage, users.update): an administrator who can reset a user's password can also remove their two-factor sign-in, never their own and never while acting as another user. The workspace's two-factor policy is a Security setting (security.update).

Demo accounts¶

An administrator can mark an existing, active local account as a demo account (Users → Manage → Edit profile → Demo account: Yes — cannot change own password). A demo pill appears next to the account. Demo users cannot change their password (This is a demo account, changing password is not supported.), the forgot-password form silently does nothing for them, and an administrator's password reset does not force them to change it afterwards. You cannot change the demo setting on your own account.

Permissions¶

Every permission is resource.action. Viewing, creating, editing and deleting are separate actions on every resource, so a role can allow exactly what a team needs - for example see notification channels but change nothing, or add and edit public endpoints but never delete one. A few resources have an extra verb for an action that is more sensitive than an ordinary edit.

Workspace-level resources (roles, security, tenant appearance) belong to the whole tenant - your workspace - not to one organization. Their permissions only take effect when the role is assigned across the whole workspace (or the user is a tenant administrator); granting them inside a single organization does nothing. The built-in Administrator preset deliberately leaves them out, so an organization administrator can never change settings that belong to the whole workspace: a tenant administrator reaches them through that status, and anyone else needs a custom role that includes them, granted workspace-wide. The same rule applies to workspace-wide notification channels, scheduled reports and trusted CAs: an organization-scoped role can manage the ones in its organization, a workspace-wide role or a tenant administrator can manage the shared ones.

Database backups and component release manifests are platform-wide concerns handled by the platform operator; they never appear in a tenant's permission matrix and cannot be put in a custom role.

Custom roles¶

Access → Roles lists every built-in role and lets a tenant administrator (or anyone holding roles.create workspace-wide) define custom roles: give the role a name and description, tick the permissions in the matrix, and save. The box under each column heading (read, create, …) ticks or clears every permission in that column you are allowed to grant, so a read-only role is one click. The role is then offered on the Users page in both pickers - per organization and workspace-wide - exactly like a built-in role, and through the API as GET /api/v1/roles / POST /api/v1/users. GET /api/v1/roles and the permission catalogue (GET /api/v1/permissions) need roles.read granted workspace-wide, or users.read; roles.read granted only in an organization opens nothing, like the dashboard's Roles page. Every role has a kind (user or api), and ?kind= narrows both lists to one kind.

A custom API role is defined on the API roles tab with the same editor and the same rules, except for what it cannot hold and for what an edit does to the keys that use it; see Custom API roles. Changing a user role never changes what a key can do.

Rules the editor enforces:

• You can only grant permissions you hold yourself, everywhere the role applies. A tenant administrator can grant anything. Anyone else building a role that applies to all organizations must hold each permission workspace-wide; a role confined to particular organizations only needs them held in each of those organizations. The greyed-out boxes in the matrix are the ones outside your own reach. Lifting a role's organization restriction, or adding an organization to it, is checked the same way.
• Permissions marked with a small ▲ in the matrix (users.create, users.update, roles.*, api_keys.create / update / admin, identity_providers.create / update) let their holder delegate authority: assign roles, mint API keys, define roles, or map identity-provider claims. See Delegation is bounded for what a holder can and cannot hand out. Pairing one of these with a narrow permission set is safe; pairing it with Administrator-level permissions makes its holders able to appoint further administrators.
• Platform permissions and the reserved role names (administrator, platform_*, …) are never available.
• A role's key (alert_desk, derived from the name you typed) is fixed once created, because identity-provider mappings and API clients refer to it. Rename or re-permission the role freely; the key stays.
• Deleting a role removes it from every user who held it and from every identity-provider mapping that named it. The users themselves are untouched; a user whose only role was deleted simply has no access until another is granted.
• Taking authority out of a role counts as changing every user who holds it. You can remove permissions or organizations from a role, or delete it, only if you hold at least the permissions of each of those users, as in Who can manage whom; tenant administrators always can. Otherwise the Roles page shows the role's current permissions as fixed and its Delete as unavailable, and the API answers 403 You can only remove permissions from a role whose users' permissions you hold yourself. The message doesn't name the users. Renaming a role, adding to it, and changing a role nobody holds are not affected.
• Every create, edit and delete is written to the activity log (role.create, role.update, role.delete) with the full permission list and the organizations the role applies to.

Delegation is bounded¶

Granting someone the ability to manage users, keys or identity providers never lets them make anyone - themselves included - more powerful than they are. CertIntel applies the same guardrail most platforms do (GitLab will not let you grant a role above your own, Discord only lets you assign roles below your highest one, Keycloak and Azure RBAC bound which roles a delegate may hand out):

• Hold it yourself. A role you assign to a user in an organization may only carry permissions you hold in that organization; a workspace-wide grant needs workspace-wide holdings. Inside an organization, a role is measured by what it can be used for there: its workspace-level permissions (roles, security, tenant appearance) never apply in an organization, so you need not hold them to grant it. That is why an organization Administrator can grant Auditor in their organization, and still outranks the Auditor afterwards; a permission that does apply there (for example activity.read) still has to be yours. The same applies to identity-provider claim mappings and fallback roles, which are standing grants to whoever signs in. The API answers 403 naming the missing permissions.
• Outrank nobody you change. Changing another user, removing permissions from a custom role a user holds or deleting that role, or revoking or deleting another API key, needs at least that user's or key's authority; see Who can manage whom. For a key that means the key permission (api_keys.delete, or api_keys.admin for a key with the API administrator role) in the key's own organization - workspace-wide for a key not confined to one - plus every permission the key holds there.
• Not on your own account. Only a tenant administrator may change their own roles, whatever users.update they hold.
• API keys carry only what you have. A key with an API role can do what the role's permissions allow, so creating, rotating or re-enabling one, or changing its role, requires holding every permission the key holds (and, for a new role, will hold) in the key's organization - the person who learns the secret inherits the key's authority. Editing an API role is checked against every key that uses it. A key that is allowed to request private-CA certificates can only be rotated by someone holding private_ca.update (or api_keys.admin) there.
• Not while acting as a tenant. A platform operator inside a time-boxed act-as session (or holding an act-as key) cannot create or reveal anything that would outlive the session, or change who can reach the tenant: API keys (create, rotate, reactivate); agents (approve an enrollment, re-register, allow private-CA issuance); install tokens (create, mint a one-time token, show, rotate, reactivate); DNS delegations (create, rotate the secret, re-enable); alert destinations, alert contacts and scheduled reports (add or change); private-CA issuance and private-key downloads; identity providers and their role mappings; an agent's sealing key; users (create, enable, change email, organization memberships or roles, grant tenant-wide authority, reset a password or two-factor sign-in). These answer While acting as a tenant you cannot … The tenant's own administrator has to do this. Revoking, disabling and deleting stay open, because they only take access away. Everything done in the session is logged as <operator> (acting as …). Act-as keys cannot be rotated or re-enabled by anyone.

Tenant administrators are exempt from the first four rules: they can already do anything in the tenant (only a platform administrator changes a platform administrator).

Confining a role to particular organizations¶

Below the permission matrix, Applies to decides which organizations the role can ever reach:

• All organizations (the default) makes the role behave like a built-in one: granted in an organization it covers that organization; granted workspace-wide it covers every organization.
• Only these organizations confines the role to the organizations you tick. Granted workspace-wide, it covers exactly those organizations and no other - so a role that "lets the team work in A and B but not C and D" is one role, scoped to A and B, assigned once from the Users page. Granted per organization, it can only be granted inside the organizations it names; the Users page offers it only there, and the API answers 409 elsewhere.

The custom roles table shows what each role applies to. Narrowing a role later takes effect for every holder at their next request; if every organization a scoped role named is deleted the role reaches nothing until you edit it (it never silently widens to the whole workspace). Only someone with workspace-wide roles.update authority can change the restriction - the same rule as for the permissions themselves.

The REST API mirrors the page: GET /api/v1/permissions returns the catalogue grouped as the matrix shows it, POST /api/v1/roles creates a role from {"name", "description", "permissions": ["targets.read", …], "organizations": ["ops-a", "ops-b"]} (organization slugs or ids; omit or send null for all organizations), and PATCH / DELETE /api/v1/roles/{id} edit or remove it. In a PATCH, leaving organizations out keeps the current restriction, a list replaces it and an explicit null lifts it. Every role answers with organization_scoped and the organizations it is confined to. Built-in roles are read-only and answer 404 to edits.

A role confined to organizations you reach none of (as an organization Administrator, or while switched into one client) does not exist for you, whether you ask for it by id or by key: GET /api/v1/roles/{id} answers 404 Role not found., and granting it by key answers 409 Unknown roles: […] on a user, or Unknown role: … as an identity provider's fallback role or role mapping, exactly like a key that does not exist. For a role you can see, organizations lists only the organizations you reach.

SSO and roles¶

If your organization signs in through an identity provider, role assignment is driven by claims in the provider's token instead of - or alongside - roles assigned directly in CertIntel, and is fully resynced on every login. See OIDC / SSO overview for the full model, including the CertIntel.* claim convention that maps directly to the roles above.

Plans and limits¶

Each tenant has an entitlement plan controlling limits on the number of public endpoints, internal certificates, Delegated DNS-01 records, approved agents, users and organizations, and features such as alert destinations, Certificate Transparency monitoring, SSO, activity-log retention, Appearance and MSP (client co-branding, switch into client, client dashboard; see MSP mode). The plans, their prices and every limit are listed on Plans, pricing and limits. The dashboard Overview shows a Plan usage & limits table with the number allowed and used for each limit type and an At limit marker. If an action is blocked by a plan limit, the error explains which limit was hit; contact your CertIntel administrator or provider to adjust it.