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.api_key = "sk_example_123456789"
end

WorkOS.client.multi_factor_auth.create_user_auth_factor(
  userland_user_id: "user_01E4ZCR3C56J083X43JQXF3JK5",
  type: "totp"
)

 from workos import WorkOSClient

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

client.multi_factor_auth.create_user_auth_factor(
    userland_user_id="user_01E4ZCR3C56J083X43JQXF3JK5", type="totp"
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.MultiFactorAuth().CreateUserAuthFactor(context.Background(), "user_01E4ZCR3C56J083X43JQXF3JK5", &workos.MultiFactorAuthCreateUserAuthFactorParams{
		Type: "totp",
	})
	if err != nil {
		panic(err)
	}
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->multiFactorAuth()
    ->createUserAuthFactor(
        userlandUserId: "user_01E4ZCR3C56J083X43JQXF3JK5",
        type: "totp",
    );

 import com.workos.WorkOS;
import com.workos.multifactorauth.MultiFactorAuthApi.CreateUserAuthFactorOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateUserAuthFactorOptions options =
    CreateUserAuthFactorOptions.builder().type("totp").build();

workos.multiFactorAuth.createUserAuthFactor("user_01E4ZCR3C56J083X43JQXF3JK5", options);

 using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.MultiFactorAuth.CreateUserAuthFactorAsync("user_01E4ZCR3C56J083X43JQXF3JK5",
                                                       new MultiFactorAuthCreateUserAuthFactorOptions {
                                                           Type = "totp",
                                                       });

 use workos::Client;
use workos::multi_factor_auth::CreateUserAuthFactorParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .multi_factor_auth()
        .create_user_auth_factor(
            "user_01E4ZCR3C56J083X43JQXF3JK5",
            CreateUserAuthFactorParams {
                type_: "totp".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}

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.api_key = "sk_example_123456789"
end

WorkOS.client.multi_factor_auth.list_user_auth_factors(userland_user_id: "user_01E4ZCR3C56J083X43JQXF3JK5")

 from workos import WorkOSClient

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

client.multi_factor_auth.list_user_auth_factors(
    userland_user_id="user_01E4ZCR3C56J083X43JQXF3JK5"
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.MultiFactorAuth().ListUserAuthFactors(context.Background(), "user_01E4ZCR3C56J083X43JQXF3JK5")
	if err != nil {
		panic(err)
	}
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->multiFactorAuth()
    ->listUserAuthFactors(userlandUserId: "user_01E4ZCR3C56J083X43JQXF3JK5");

 import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.multiFactorAuth.listUserAuthFactors("user_01E4ZCR3C56J083X43JQXF3JK5");

 using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.MultiFactorAuth.ListUserAuthFactorsAsync("user_01E4ZCR3C56J083X43JQXF3JK5");

 use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .multi_factor_auth()
        .list_user_auth_factors("user_01E4ZCR3C56J083X43JQXF3JK5")
        .await?;

    Ok(())
}

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`