Skip to main content

​
Sign-in methods

Users authenticate in one of two ways:
  • E-mail and password, with optional multi-factor authentication.
  • An external identity provider — Google, GitHub or Microsoft Entra ID.
Accounts created through an identity provider have no password until one is set. Because multi-factor authentication requires a password, users who signed up with Google or GitHub are prompted to set one before they can enable MFA. The procedure is in Security settings. In a self-hosted deployment, each identity provider is off by default and enabled by the on-prem administrator with a client ID and secret from the registered OAuth application — see Single sign-on. Enabling a provider is deployment-wide; there is no per-organisation provider configuration.

​
Multi-factor authentication

MFA uses time-based one-time passwords (TOTP) and works with any standard authenticator app, such as Google Authenticator or Microsoft Authenticator. Users enrol by scanning a QR code (or entering the key manually) and confirming a 6-digit code. Enrolment is per user and self-service — each user enables it from their own security settings. Disabling it also requires a valid code, so an attacker holding only the password cannot turn it off.
There is no organisation-level setting to require MFA for all members. If your policy mandates MFA, enforce it through your identity provider by making SSO the only sign-in path for your users.

​
Sessions and password lifecycle

The values below are the defaults for a self-hosted deployment, set in the environment file at install time: Password expiration means users are required to change their password periodically rather than indefinitely reusing one. Password reset relies on outbound e-mail, so a self-hosted deployment must have SMTP configured for self-service recovery to work — without it, an administrator has to intervene. Administrators can also prompt a user to reset their password from the members table, which raises a notification in that user’s notification centre. See Manage members.

​
The permission model

Access is governed on two independent axes.

​
Organisation role

Every user has one role, which determines their administrative rights and how widely they can share playbooks: Each organisation must retain at least one Admin. An admin cannot change their own role or remove themselves from the organisation, which prevents an organisation from being left without an administrator.

​
Workspace membership

Role governs what a user can do; workspace membership governs which data they can do it to. Playbooks, executions, assets, integrations and presets are scoped to a workspace, and only its members can reach them — an organisation Admin does not implicitly see the contents of a workspace they are not a member of. Workspaces has the details.

​
Administrative access in self-hosted deployments

Self-hosted deployments have an additional on-prem administrator account, created during installation and separate from any organisation. It manages licensing, deployment-wide settings, organisations and audit logs. This account is created with a default password that must be changed at first login. It has no organisation membership and therefore no access to any workspace’s playbook data.
Treat the on-prem administrator as a break-glass account. It can create organisations and add members without invitation, and its recovery procedure requires shell access to the host — see Resetting the administrator password.
Self-hosted deployments can also add members to an organisation directly, without an e-mail invitation. Accounts created this way start with a known default password and are forced to change it at first login. The behaviour and its failure cases are documented in Invite members.

​
API access

The REST API authenticates with an API key sent in the x-cymph-api-key header. Keys are created by individual users from their own settings, are named, and are issued with an expiration period. A key acts on behalf of the user who created it, so it inherits that user’s role and workspace membership — revoking a user’s access revokes what their keys can reach. See API access.