View Source WorkOS.MFA (WorkOS SDK for Elixir v0.4.0)

The MFA module provides convenience methods for working with the WorkOS MFA platform. You'll need a valid API key.

See https://workos.com/docs/mfa

Link to this section Summary

Functions

Creates a Challenge for an Authentication Factor.

Deletes an Authentication Factor.

Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge.

Gets an Authentication Factor.

Verify Authentication Challenge.

Link to this section Functions

Link to this function

challenge_factor(params, opts \\ [])

View Source

Creates a Challenge for an Authentication Factor.

parameters

Parameters

  • params (map)
    • authentication_factor_id (string) The unique ID of the Authentication Factor to be challenged.
    • sms_template (string) Optional template for SMS messages. Only applicable for sms Factors. Use the {{code}} token to inject the one-time code into the message. E.g., Your Foo Corp one-time code is {{code}}.

examples

Examples

iex> WorkOS.MFA.challenge_factor(%{
...>  authentication_factor_id: "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
...> })

{:ok, %{
  "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"
}}

iex> WorkOS.MFA.challenge_factor(%{
...>  authentication_factor_id: "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
...>  sms_template: "Your Foo Corp one-time code is {{code}}"
...> })

{:ok, %{
  "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"
}}
Link to this function

delete_factor(id, opts \\ [])

View Source

Deletes an Authentication Factor.

parameters

Parameters

  • id (string) The unique ID of the Authentication Factor to delete.

examples

Examples

iex > WorkOS.MFA.delete_factor("auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ")
Link to this function

enroll_factor(params, opts \\ [])

View Source

Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge.

parameters

Parameters

  • params (map)
    • type (string) The type of factor you wish to enroll. Must be one of 'totp' or 'sms'.
    • totp_issuer (string) An identifier for the organization issuing the challenge. Should be the name of your application or company. Required when type is totp.
    • totp_user (string) An identifier for the user. Used by authenticator apps to label connections. Required when type is totp.
    • phone_number (string) A valid phone number for an SMS-enabled device. Required when type is sms.

examples

Examples

iex> WorkOS.MFA.enroll_factor(%{
...>  type: "totp",
...>  totp_issuer: "Foo Corp",
...>  totp_user: "user_01GBTCQ2"
...> })

{:ok, %{
  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: %{
    qr_code: "data:image/png;base64,{base64EncodedPng}",
    secret: "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
    "uri": "otpauth://totp/FooCorp:user_01GB"
  }
}}

iex> WorkOS.MFA.enroll_factor(%{
...>  type: "sms",
...>  phone_number: "+15555555555"
...> })

{:ok, %{
  object: "authentication_factor",
  id: "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
  created_at: "2022-02-15T15:14:19.392Z",
  updated_at: "2022-02-15T15:14:19.392Z",
  type: "sms",
  sms: %{
    phone_number: "+15555555555"
  }
}}
Link to this function

get_factor(id, opts \\ [])

View Source

Gets an Authentication Factor.

parameters

Parameters

  • id (string) The unique ID of the Authentication Factor to retrieve.

examples

Examples

iex > WorkOS.MFA.get_factor("auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ")

  {:ok, %{
    "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": {
      "qr_code": "data:image/png;base64,{base64EncodedPng}",
      "secret": "NAGCCFS3EYRB422HNAKAKY3XDUORMSRF",
      "uri": "otpauth://totp/FooCorp:alan.turing@foo-corp.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp"
    }
  }
Link to this function

verify_challenge(params, opts \\ [])

View Source

Verify Authentication Challenge.

parameters

Parameters

  • params (map)
    • authentication_challenge_id (string) The unique ID of the Authentication Challenge to be verified.
    • code (string) The 6-digit code to be verified.

examples

Examples

iex > WorkOS.MFA.verify_challenge(%{
... >  authentication_challenge_id: "auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5",
... >  code: "123456"
... > })

{:ok, %{
  "challenge": %{
    "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",
  },
  "valid": true
}}