Authentication and MFA

Sign in to Integraph, set up multi-factor authentication, configure org-wide MFA policy, and manage API keys.

Overview

Integraph accounts use email and password authentication with optional multi-factor authentication (MFA). Organisation owners can require an authenticator app for members who sign in with an Integraph password; members who sign in through Google or Microsoft have their MFA governed by that identity provider.

Signing in

The sign-in page offers an Integraph email and password, or single sign-on through Google or Microsoft. Social sign-in hands you off to the hosted login page and returns you to Integraph once the identity provider confirms who you are.

:::note[Hosted login page rebranded — September 2026 (#6311)] The hosted login page (Cognito Managed Login v2) now carries Integraph’s own logo and colours in place of the default styling, with a corrected light-mode appearance and the Microsoft logo on the Microsoft sign-in button. The Google and Microsoft buttons keep a fixed order rather than one Cognito assigns per session — Cognito’s per-provider ordering setting does not accept the provider names this platform uses, so the order is left unset instead of being sorted incorrectly. This is a visual change only; email/password sign-in and MFA are unaffected. :::

:::note[Sign-in return target validated and carried through social sign-in — September 2026 (#6304)] Where you land after signing in — for example, back at the MCP OAuth connection flow you started from, rather than the dashboard — is now validated as a same-origin path before use, and is carried through a Google or Microsoft sign-in the same way it already was for a password sign-in. Previously, starting an SSO sign-in from the MCP OAuth façade (a client app opening /login?returnTo=/oauth/authorize?...) always landed you on the dashboard after Google or Microsoft confirmed your identity, because the return target was dropped for the social sign-in leg; you had to restart the MCP connection from the dashboard to complete it. You now return to the OAuth authorisation screen and can finish connecting the MCP client in one pass. A return target that is not a same-origin path — including an open-redirect attempt disguised as one — falls back to the dashboard rather than being followed. :::

Multi-factor authentication (MFA)

MFA adds a second verification step beyond your password. A time-based one-time password (TOTP) app — Google Authenticator, Authy, 1Password, or any RFC 6238-compatible app — is recommended.

To enrol:

1. Open the account menu and select Account settings.
2. Navigate to Security.
3. Click Enable MFA and scan the QR code with your authenticator app.
4. Enter the six-digit code from the app to confirm enrolment.

Once enrolled, each sign-in requires your password and a fresh one-time code from your app.

Your MFA enrolment status is visible on /me in the account settings page. API callers can read it from the mfaEnabled field on the GET /api/v1/auth/me response.

Org-enforced MFA

Organisation owners can require members to hold an authenticator app for Integraph password sign-ins.

That scope is the whole design. Integraph enforces the one sign-in method it controls; if your organisation signs in through Google or Microsoft, MFA for those accounts is set in your own directory, where the policy actually lives and is enforceable.

Enabling the requirement

1. Open the org’s Security tab (all members can open it; only Owners can change anything on it).
2. Toggle Require an authenticator app for password sign-ins to on.
3. Confirm the change.

Members who sign in with an Integraph password and have not enrolled see a blocking gate on their next request, and must enrol before they can use the platform. Members who are already enrolled are unaffected.

What the policy does and does not cover

Integraph cannot check whether a member used MFA at Google or Microsoft; those providers do not report it to us, and we do not guess. Rather than block every federated member for a fact we cannot establish, the policy leaves those sign-ins to the directory that governs them.

:::caution[If you federate, set the MFA policy at your identity provider] Turning this on does not put an MFA requirement on members who sign in with Google or Microsoft. To cover them, enforce MFA in Google Workspace or Microsoft Entra. Both providers also allow anyone to create a personal account on any email address, so a member could in principle sign in with a personal Google account on their work address — enforcing MFA in your directory does not prevent that. :::

Self-lockout refusal

An Owner cannot turn the policy on when their own current session would fail it — a password session with no authenticator app. The request is refused with 422 and the code mfa_policy_owner_not_compliant, because applying it would lock them out of the organisation they govern. Enrol first, then try again.

Turning the requirement off is always allowed, so the policy can never become stuck on.

If you are blocked

Sign out, sign in again with your Integraph email and password, then set up or verify an authenticator app. Re-authenticating comes first: an authenticator app cannot be enrolled from a Google or Microsoft session, and a session Integraph could not classify is treated as a password sign-in until you sign in through the password flow.

If you are a new member who has not yet accepted the Terms of Service, Privacy Policy and design-aid acknowledgement, the two prompts are sequenced rather than stacked: enrol first, and the acceptance prompt follows. Recording that acceptance is permitted while the MFA gate is up — it is a prerequisite to using Integraph at all, not something the policy withholds.

Security tab

The Security tab on an organisation’s settings page can be opened by any member; only the Owner can change anything on it. It shows:

• The MFA policy toggle
• The API-key exclusion notice
• For the Owner only, each member’s authenticator-app enrolment status

That roster reports enrolment, not compliance, and it is deliberately limited: Integraph does not show how another member signs in, so the list cannot tell you which members use a password (and therefore need to enrol) and which sign in through your identity provider.

API Keys tab

The API Keys tab is visible to anyone holding a Pro subscription granted by the organisation you are viewing, and to that organisation’s admins and owners. Everyone else does not see the tab; direct API callers receive a 403 Forbidden response rather than an empty list when they attempt to reach the key-management endpoints.

Creating a key requires a Pro subscription on your own account, granted by this organisation — your role does not substitute for it. A key authenticates as the person who created it, so one created by an admin who holds no Pro subscription themselves would be refused on every call; the Create button is disabled for them rather than handing over a key that cannot work. If you are an admin who has assigned Pro to someone else and want a key of your own, assign yourself a Pro seat in the Billing tab.

What you can see and revoke depends on your role:

A key that belongs to another member is reported as not found to someone who is not an admin, rather than as forbidden — so a key’s existence is never disclosed to a colleague who cannot manage it.

API keys grant programmatic access to the Integraph API using the same permissions as your account. Key scopes listed in the management UI are advisory metadata — they describe intended use, but do not narrow the key’s actual permissions (see API reference for details on scope semantics).

:::note[API key org scoping — fall-open on HTTP 500 closed — September 2026 (#5455, #5474)] API key authentication now fails closed when the organisation-scope resolution step returns an HTTP 500. Previously, a 500 during that resolution step was treated as a fall-open condition — the key was admitted rather than refused — which could allow a key to operate without an established org context. The fix refuses authentication on any unhandled error from the org-scope step, returning 401 Unauthorized. If you see unexpected 401 responses from an API key that was previously working, confirm the key’s associated organisation is still active and that the org-scope resolution endpoint is reachable. :::

:::note[API key management aligned to Pro entitlement, not role — September 2026 (#6166, #6167)] The API Keys tab and key-management endpoints now gate on your own Pro entitlement, not on an org-wide flag. Previously, Create / List / Revoke required admin or owner — which admitted a Pro-less admin who could mint keys that were then refused on every call, while the member whose seat was actually funded was blocked outright. The rules are now:

• Create requires a Pro seat granted to you by this org, whatever your role. An admin without a seat sees the tab (to manage other keys) but the Create button is disabled and explains why. A Pro-holding viewer can create.
• List and revoke — your own keys for a non-admin; every key in the org for an admin or owner, with or without Pro.
• A key that belongs to another member is reported as not found rather than forbidden to someone without admin access — a key’s existence is never disclosed to a colleague who cannot manage it.

The table above reflects the current rules. :::

:::note[API Keys table shows who created each key — September 2026 (#6176, #6187)] The API Keys table now includes a Created by column showing the display name of the member who created each key. The creator is stored on the key at mint time and is always present — createdBy is a required field on the response and is never null. :::

Forgot password

To reset your password:

1. On the sign-in page, click Forgot password.
2. Enter your email address and click Send reset link.
3. Open the email and follow the link to set a new password.

:::caution[Dispatch errors are now surfaced — September 2026 (#5332)] The forgot-password endpoint now refuses to respond with a success message when it cannot confirm that the reset email was dispatched. Previously, a dispatch failure — for example, a transient email-provider error — returned 200 OK, giving false confidence that the email had been sent.

If you see an error on the “Forgot password” step rather than the usual “check your inbox” confirmation, the platform could not confirm dispatch. Wait a moment and try again. If the error persists, contact support with your email address and the approximate time you attempted the reset. :::

Related pages

• Getting started with Integraph — account setup and first project
• Organisations — org member management and roles
• API reference — full route listing