Multi-Factor Authentication (planned)

Before you begin

• Nothing to prepare for MFA itself; it cannot be enabled.
• If you want the foundation in place: an environment whose Authentication tab shows ready, which gives its users an isolated, brute-force protected realm.
• A note of the sensitive actions in your product that would deserve step-up verification once it exists.

Install

There is nothing to install. Paycux is a plain HTTPS JSON API, so every example on this page uses curl. Console routes send the dashboard session cookie, end-user routes send the application's realm access token as a bearer credential, and agent routes send the short-lived agent token. The routes that exist today are listed on What exists today.

1# Console routes carry the dashboard session cookie set by sign-in
2curl https://api.paycux.com/v1/auth/session \
3  -H "Cookie: __Host-paycux_session=<session>"
4 
5# End-user routes carry the application's realm access token
6curl https://api.paycux.com/v1/<end-user route> \
7  -H "Authorization: Bearer <realm access token>"

Configure

There are no MFA configuration values. The values below are the identity configuration an application holds today; the planned feature would not change them.

1PAYCUX_API_BASE_URL=https://api.paycux.com
2PAYCUX_PROJECT_ID=<project id>
3PAYCUX_ENVIRONMENT_ID=<environment id>
4PAYCUX_REALM_ID=<realm id>

Then, in the dashboard:

1. 1There is no MFA section in the console today.
2. 2The Authentication tab of an environment shows the realm the planned feature would attach to: status, issuer, client ID and realm ID.
3. 3The Users tab lists identities read-only. It shows no factor information because none exists.

Implement

The planned flow: a signed-in user would enrol an authenticator app on the realm's screens and receive recovery codes; an organisation could require a factor for its members; a challenge would be demanded at sign-in and, with step-up, before sensitive actions; an admin could reset a lost factor, with every change audited. No route implements any of this. The samples show only what exists.

1curl "https://api.paycux.com/v1/environments/<environment id>/auth?projectId=<project id>" \
2  --cookie "__Host-paycux_session=<session cookie>"
3 
4HTTP 200
5{
6  "setup": {
7    "realmId": "<realm id>",
8    "displayName": "Example App",
9    "status": "ready",
10    "issuer": "https://<identity host>/realms/pcx-<uuid>",
11    "clientId": "<client id>",
12    "discoveryUrl": "https://<identity host>/realms/pcx-<uuid>/.well-known/openid-configuration",
13    "lastErrorCode": null
14  }
15}
16# The full object also carries workspaceId, projectId, environmentId,
17# providerRealmName, redirectUris, logoutRedirectUris, checkoutReturnUrls,
18# revision and appliedRevision.

1curl "https://api.paycux.com/v1/identity/me" \
2  --header "Authorization: Bearer <realm access token>"
3 
4HTTP 200
5{
6  "id": "<identity id>",
7  "realmId": "<realm id>",
8  "issuer": "https://<identity host>/realms/pcx-<uuid>",
9  "subject": "<subject in the realm>",
10  "email": "ada@example.com",
11  "emailVerified": true,
12  "createdAt": "2026-10-13T09:12:44.000Z"
13}

Verify

There is nothing to verify for MFA. You can confirm the foundation.

1. 1Confirm the environment's Authentication tab shows ready.
2. 2Confirm a token from an account with an unverified e-mail is refused by GET /v1/identity/me with 403 EMAIL_UNVERIFIED.
3. 3Confirm repeated wrong passwords on the sign-in screen trigger the realm's brute-force protection.

Reference

Request and response shapes for each of these live in the API reference. Paths are relative to https://api.paycux.com.

Next steps