Multi-Factor Authentication

Enroll users in multi-factor authentication for an additional layer of security. MFA can be enabled via the Authentication page in the WorkOS dashboard.

Authentication factor

Represents an authentication factor.

Authentication factor

JSON

 {
  "object": "authentication_factor",
  "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
  "created_at": "2022-02-15T15:14:19.392Z",
  "updated_at": "2022-02-15T15:14:19.392Z",
  "type": "totp",
  "totp": {
    "issuer": "Foo Corp",
    "user": "alan.turing@example.com",
    "qr_code": "data:image/png;base64,{base64EncodedPng}",
    "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
    "uri": "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp"
  },
  "userId": "user_01FVYZ5QM8N98T9ME5BCB2BBMJ"
}

 const factor = {
  object: 'authentication_factor',
  id: 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ',
  createdAt: '2022-02-15T15:14:19.392Z',
  updatedAt: '2022-02-15T15:14:19.392Z',
  type: 'totp',
  totp: {
    issuer: 'Foo Corp',
    user: 'alan.turing@example.com',
    qrCode: 'data:image/png;base64,{base64EncodedPng}',
    secret: 'NAGCCFS3EYRB422HNAKAKY3XDUORMSRF',
    uri: 'otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp',
  },
  userId: 'user_01FVYZ5QM8N98T9ME5BCB2BBMJ',
};

 WorkOS::Factor.new <<~JSON
  {
    "object": "authentication_factor",
    "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
    "created_at": "2022-02-15T15:14:19.392Z",
    "updated_at": "2022-02-15T15:14:19.392Z",
    "type": "totp",
    "totp": {
      "issuer": "Foo Corp",
      "user": "alan.turing@example.com",
      "qr_code": "data:image/png;base64,{base64EncodedPng}",
      "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
      "uri": "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp"
    }
    "user_id": "user_01FVYZ5QM8N98T9ME5BCB2BBMJ"
  }
JSON

 from workos.types.mfa import AuthenticationFactorTotpExtended, ExtendedTotpFactor

authentication_factor_totp = AuthenticationFactorTotpExtended(
    object="authentication_factor",
    id="auth_factor_123",
    created_at="2022-02-15T15:14:19.392Z",
    updated_at="2022-02-15T15:14:19.392Z",
    type="totp",
    totp=ExtendedTotpFactor(
        issuer="WorkOS",
        user="alan.turing@example.com",
        qr_code="data:image/png;base64,{base64EncodedPng}",
        secret="NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
        uri="otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp",
    ),
    user_id="user_123",
)

 package main

import (
	"github.com/workos/workos-go/v3/pkg/mfa"
)

func main() {
	enroll := mfa.Factor{
		ID:        "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
		CreatedAt: "2022-02-15T15:14:19.392Z",
		UpdatedAt: "2022-02-15T15:14:19.392Z",
		Type:      "totp",
		TOTP: mfa.TOTPDetails{
			QRCode: "data:image/png;base64,{base64EncodedPng}",
			Secret: "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
			URI:    "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp",
		},
	}
}

 <?php

$authenticationFactor = [
    "object" => "authentication_factor",
    "id" => "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
    "created_at" => "2022-02-15T15:14:19.392Z",
    "updated_at" => "2022-02-15T15:14:19.392Z",
    "type" => "totp",
    "totp" => [
        "issuer" => "Foo Corp",
        "user" => "alan.turing@example.com",
        "qr_code" => "data:image/png;base64,{base64EncodedPng}",
        "secret" => "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
        "uri" =>
            "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp",
    ],
    "user_id" > "user_01FVYZ5QM8N98T9ME5BCB2BBMJ",
];

 import com.workos.usermanagement.models.AuthenticationFactor;
import com.workos.usermanagement.models.AuthenticationTotp;

AuthenticationFactor challenge = new AuthenticationFactor(
    "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
    "2022-02-15T15:14:19.392Z",
    "2022-02-15T15:14:19.392Z",
    "totp",
    new AuthenticationTotp("Foo Corp",
        "alan.turing@example.com",
        "data:image/png;base64,{base64EncodedPng}",
        "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
        "otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp"),
    "user_01FVYZ5QM8N98T9ME5BCB2BBMJ");

`authentication_factor`

Authentication challenge

Represents a challenge of an authentication factor.

Authentication challenge

JSON

 {
  "object": "authentication_challenge",
  "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
  "created_at": "2022-02-15T15:26:53.274Z",
  "updated_at": "2022-02-15T15:26:53.274Z",
  "expires_at": "2022-02-15T15:36:53.279Z",
  "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ"
}

 const challenge = {
  object: 'authentication_challenge',
  id: 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5',
  createdAt: '2022-02-15T15:26:53.274Z',
  updatedAt: '2022-02-15T15:26:53.274Z',
  expiresAt: '2022-02-15T15:36:53.279Z',
  authenticationFactorId: 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ',
};

 WorkOS::Challenge.new <<~JSON
  {
    "object": "authentication_challenge",
    "id": "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
    "created_at": "2022-02-15T15:26:53.274Z",
    "updated_at": "2022-02-15T15:26:53.274Z",
    "expires_at": "2022-02-15T15:36:53.279Z",
    "authentication_factor_id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ"
  }
JSON

 from workos.types.mfa import AuthenticationChallenge

authentication_challenge = AuthenticationChallenge(
    object="authentication_challenge",
    id="auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
    created_at="2022-02-15T15:26:53.274Z",
    updated_at="2022-02-15T15:26:53.274Z",
    expires_at="2022-02-15T15:36:53.279Z",
    authentication_factor_id="auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
)

 package main

import (
	"github.com/workos/workos-go/v2/pkg/mfa"
)

func main() {
	challenge := mfa.Challenge{
		ID:        "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
		Object:    "authentication_challenge",
		CreatedAt: "2022-02-15T15:26:53.274Z",
		UpdatedAt: "2022-02-15T15:26:53.274Z",
		ExpiresAt: "2022-02-15T15:36:53.279Z",
		FactorId:  "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
	}
}

 <?php

$authenticationChallenge = [
    "object" => "authentication_challenge",
    "id" => "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
    "created_at" => "2022-02-15T15:26:53.274Z",
    "updated_at" => "2022-02-15T15:26:53.274Z",
    "expires_at" => "2022-02-15T15:36:53.279Z",
    "authentication_factor_id" => "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
];

 import com.workos.usermanagement.models.AuthenticationChallenge;

AuthenticationChallenge challenge =
    new AuthenticationChallenge("auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
        "2022-02-15T15:26:53.274Z",
        "2022-02-15T15:26:53.274Z",
        "2022-02-15T15:36:53.279Z",
        "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ");

`authentication_challenge`

Enroll an authentication factor

Enrolls a user in a new authentication factor.

Request

cURL

 curl --request POST \
  --url https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/auth_factors \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<BODY
  {
    "type": "totp",
    "totp_issuer": "Foo Corp",
    "totp_user": "bob@example.com"
  }
BODY

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const { authenticationFactor, authenticationChallenge } =
  await workos.userManagement.enrollAuthFactor({
    userId: 'user_01E4ZCR3C56J083X43JQXF3JK5',
    type: 'totp',
    totpIssuer: 'WorkOS',
    totpUser: 'bob@example.com',
  });

 require "workos"

WorkOS.configure do |config|
  config.key = "sk_example_123456789"
end

authentication_factor_and_challenge =
  WorkOS::UserManagement.enroll_auth_factor(
    user_id: "user_01E4ZCR3C56J083X43JQXF3JK5",
    type: "totp",
    totp_issuer: "WorkOS",
    totp_user: "bob@example.com"
  )

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

factor_and_challenge = workos_client.user_management.enroll_auth_factor(
    user_id="user_01E4ZCR3C56J083X43JQXF3JK5",
    type="totp",
    totp_issuer="WorkOS",
    totp_user="bob@example.com",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v2/pkg/usermanagement"
)

func main() {
	usermanagement.SetAPIKey(
		"sk_example_123456789",
	)

	response, err := usermanagement.EnrollAuthFactor(
		context.Background(),
		usermanagement.EnrollAuthFactorOpts{
			User:       "user_01E4ZCR3C56J083X43JQXF3JK5",
			Type:       "totp",
			TOTPIssuer: "WorkOS",
			TOTPUser:   "bob@example.com",
		},
	)
}

 <?php

WorkOS\WorkOS::setApiKey("sk_example_123456789");

$userManagement = new WorkOS\UserManagement();

$authenticationFactorAndChallenge = $userManagement->enrollAuthFactor(
    "user_01E4ZCR3C56J083X43JQXF3JK5",
    "totp",
    "WorkOS",
    "bob@example.com"
);

 import com.workos.WorkOS;
import com.workos.usermanagement.builders.EnrolledAuthenticationFactorOptionsBuilder;
import com.workos.usermanagement.models.EnrolledAuthenticationFactor;

WorkOS workos = new WorkOS("sk_example_123456789");

EnrolledAuthenticationFactor factorAndChallenge =
    workos.userManagement.enrollAuthFactor("user_01E4ZCR3C56J083X43JQXF3JK5",
        new EnrolledAuthenticationFactorOptionsBuilder()
            .totpUser("bob@example.com")
            .totpIssuer("WorkOS")
            .build());

POST

`/user_management/users/:userlandUserId/auth_factors`

`Parameters`

`Returns`

List authentication factors

Lists the authentication factors for a user.

Request

cURL

 curl https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/auth_factors \
  --header "Authorization: Bearer sk_example_123456789"

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const authFactors = await workos.userManagement.listAuthFactors({
  userId: 'user_01E4ZCR3C56J083X43JQXF3JK5',
});

console.log(authFactors.data);

 require "workos"

WorkOS.configure do |config|
  config.key = "sk_example_123456789"
end

auth_factors = WorkOS::UserManagement.list_auth_factors(
  user_id: "user_01E4ZCR3C56J083X43JQXF3JK5"
)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

auth_factors = workos_client.user_management.list_auth_factors(
    user_id="user_01E4ZCR3C56J083X43JQXF3JK5"
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v2/pkg/usermanagement"
)

func main() {
	usermanagement.SetAPIKey(
		"sk_example_123456789",
	)

	response, err := usermanagement.ListAuthFactors(
		context.Background(),
		usermanagement.ListAuthFactorsOpts{
			User: "user_01E4ZCR3C56J083X43JQXF3JK5",
		},
	)
}

 <?php

WorkOS\WorkOS::setApiKey("sk_example_123456789");

$userManagement = new WorkOS\UserManagement();

$authFactors = $userManagement->listAuthFactors(
    "user_01E4ZCR3C56J083X43JQXF3JK5"
);

 import com.workos.WorkOS;
import com.workos.usermanagement.models.AuthenticationFactors;

WorkOS workos = new WorkOS("sk_example_123456789");

AuthenticationFactors authFactors =
    workos.userManagement.listAuthFactors("user_01E4ZCR3C56J083X43JQXF3JK5");

GET

`/user_management/users/:userlandUserId/auth_factors`

`Parameters`

`Returns` `object`

Email verification Continue to the next section

Up next

Multi-Factor Authentication

Authentication factor

authentication_factor

object: "authentication_factor"

id: string

created_at: string

updated_at: string

type: "totp"

totp: object

issuer: string

user: string

qr_code: string

secret: string

uri: string

user_id: string

Authentication challenge

authentication_challenge

object: "authentication_challenge"

id: string

created_at: string

updated_at: string

expires_at: string

authentication_factor_id: string

Enroll an authentication factor

/user_management/users/:userlandUserId/auth_factors

type: "totp"

totp_issuer?: string

totp_user?: string

totp_secret?: string

Parameters

userlandUserId: string

Returns

authentication_factor: object

authentication_challenge: object

List authentication factors

/user_management/users/:userlandUserId/auth_factors

Parameters

userlandUserId: string

before?: string

after?: string

limit?: integer

order?: "normal" | "desc" | "asc"

Returns object

object: "list"

data: object[]

list_metadata: object

`authentication_factor`

`authentication_challenge`

`/user_management/users/:userlandUserId/auth_factors`

`Parameters`

`Returns`

`/user_management/users/:userlandUserId/auth_factors`

`Parameters`

`Returns` `object`