Recovery Codes

The JavaScript SDK provides methods to view and manage a Member's recovery codes. These methods can be used to allow your Members to complete MFA flows in case they lose recovery code backed factors like TOTP (Time-based One-Time Passcodes). The SDK also allows you to view or rotate a Member's recovery codes for a fully authenticated Member.

Methods

The SDK provides methods that can be used to view and manage a Member's recovery codes.

To call these methods, a recovery code backed authentication factor such as TOTP must be configured on the SDK Configuration page of the Stytch dashboard.

Recovery Codes Recover

The Recovery Codes Recover method wraps the Recovery Codes Recover API endpoint. It takes a single recovery_code parameter, which is a recovery code that was previously generated for the Member. Calling the recover endpoint will consume the recovery code and authenticate the Member, minting a new session for them.

Currently, recovery codes are only generated when a Member enrolls in TOTP as their secondary MFA factor, and as such authenticate members in place of a stytch.totps.authenticate().

If neither a Member Session nor an intermediate session token is present, this method will fail.

If this method succeeds, the Member will be logged in, granted an active session, and the session cookies will be minted and stored in the browser.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchMemberSession hook if you are using React.

Method parameters

recovery_code* string
import React, { useCallback, useState } from 'react';
import { useStytch } from '@stytch/b2b/react';

export const Recover = () => {
  const stytchClient = useStytch();
  const [recoveryCode, setRecoveryCode] = useState('');

  const recover = useCallback(
    (e) => {
      e.preventDefault();
      stytch.recoveryCodes.recover({ code: recoveryCode, session_duration_minutes: 60 });
    },
    [stytchClient, recoveryCode],
  );

  const handleChange = useCallback((e) => {
    setRecoveryCode(e.target.value);
  }, []);

  return (
    <form>
      <label for="recovery-code">Enter code</label>
      <input id="recovery-code" value={recoveryCode} onChange={handleChange} />
      <button onClick={recover} type="submit">
        Submit
      </button>
    </form>
  );
};

RESPONSE

200
{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "session_jwt": "example_jwt",
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "member_session": {...},
  "member": {...},
  "organization": {...},
  "recovery_codes_remaining": 9
}

Rotate Recovery Codes

The Rotate Recovery Codes method wraps the Rotate Recovery Codes API endpoint.

Rotation requires a logged-in Member Session, as both organization_id and member_id will be inferred from the session. All existing recovery codes will be invalidated and new ones will be generated.

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react/b2b';

export const Rotate = () => {
  const stytchClient = useStytch();

  const trigger = useCallback(() => {
    stytchClient.recoveryCodes.Rotate();
  }, [stytchClient]);

  return <button onClick={trigger}>Rotate recovery codes</button>;
};

RESPONSE

200
{
	"member": {...},
	"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
	"organization": {...},
	"recovery_codes": "[
    "ckss-2skx-ebow",
    "spbc-424h-usy0",
    "hi08-n5tk-lns5",
    "1n6i-l5na-8axe",
    "aduj-eufq-w6yy",
    "i4l3-dxyt-urmx",
    "ayyi-utb0-gj0s",
    "lz0m-02bi-psbx",
    "l2qm-zrk1-8ujs",
    "c2qd-k7m4-ifmc"
  ]",
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}

Get Recovery Codes

The Get Recovery Codes method wraps the Get Recovery Codes API endpoint. Both the organization_id and member_id for this request will be inferred from the current Member's session.

import React, { useCallback } from 'react';
import { useStytch } from '@stytch/react/b2b';

export const GetRecoveryCodes = () => {
  const stytchClient = useStytch();

  const getRecoveryCodes = () => {
    stytchClient.recoveryCodes.get();
  }

  return <button onClick={getRecoveryCodes}>Get Recovery Codes</button>;
};

RESPONSE

200
{
	"member": {...},
	"member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
	"organization": {...},
	"recovery_codes": "[
        "ckss-2skx-ebow",
        "spbc-424h-usy0",
        "hi08-n5tk-lns5",
        "1n6i-l5na-8axe",
        "aduj-eufq-w6yy",
        "i4l3-dxyt-urmx",
        "ayyi-utb0-gj0s",
        "lz0m-02bi-psbx",
        "l2qm-zrk1-8ujs",
        "c2qd-k7m4-ifmc"
    ]",
	"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
	"status_code": 200
}