Authy User Client

Access your Authy TOTP secrets! 🔐

Overview

So you want to migrate from Authy to another 2FA provider?

Or you're constrained to use Authy's proprietary TOTP implementation with a service that don't support standard 2FA (looking at you SendGrid) but you want a way to use it with your preferred 2FA provider or password manager?

Don't look any further, this library got you covered! 😎

Installation

You need Node.js for this program to run.

Install the CLI globally:

npm install -g authy-user-client

Install as a Node.js library:

npm install authy-user-client

Usage

Dump all the secrets! 🥳

The primary command that will more likely do everything you need:

authy-user-client dump

1. Retrieve the Authy ID from a country code and phone number, creating a new Authy account if necessary.
2. Register a new Authy device for that account using the selected method (push, call or SMS).
3. Retrieve all the apps registered for that account and for each of them, show a standard TOTP URI that can be imported in your favorite app.

If you want more fine-grained control, you can use the following individual commands.

Check a Authy user status

authy-user-client check-user-status <country-code> <phone-number>

This will give you the Authy ID for the given phone number if registered.

Create a new user

authy-user-client create-user <email> <country-code> <phone-number>

If the user didn't already have an Authy ID during the previous check, you need to create it first with this command.

Start device registration

authy-user-client registration start <authy-id> (push | call | sms)

Start the registration process for the given Authy ID using the given authentication method, between push to an existing Authy device, call or SMS to the registered phone number.

This will save the authy_id to authy-user-client-state.json so that you don't have to explicitly pass it in all the following commands.

Complete device registration

authy-user-client registration complete <pin>

End the registration with the given PIN that was sent via the previous step.

This will save the registration response to authy-user-client-state.json file so that you don't have to explicitly pass the authy_id, client_id and secret_seed in all the following commands.

List devices

authy-user-client devices list

This will show all the devices registered for this Authy account, including their ID and a number of other details.

Delete a device

authy-user-client devices rm <device-id>

Delete the given device. You won't be able to delete the device you're execute this request from.

Enable multi-device

authy-user-client multi-device enable

Enable the multi-device feature to allow adding more devices.

Disable multi-device

authy-user-client multi-device disable

Disable the multi-device feature to restrict access to the currently registered devices.

Sync

authy-user-client sync

Sync the Authy state, effectively retrieving all the registered apps including their TOTP secret and settings.

API

If you want to use this package as a Node.js library. 🧑‍💻

const authyUserClient = require('authy-user-client')

Get OTP

const otp = await authy.getOtp(secretSeed)

Get a 7 digits Authy OTP code from the given hex secret.

Get OTPs

const { otp1, otp2, otp3 } = await authy.getOtps(secretSeed)

Get the 3 next OTP intervals. Convenience method for a number of API requests that require we send those 3 OTPs.

Check a Authy user status

await authy.checkUserStatus({ country_code: '1', cellphone: '1234567890' })

{
  "force_ott": false,
  "message": "active",
  "devices_count": 42,
  "authy_id": 111111111,
  "success": true
}

Or if the user doesn't exist yet:

{
  "force_ott": false,
  "message": "new",
  "success": true
}

Create a new user

await authy.createUser({
  email: '[email protected]',
  country_code: '1',
  cellphone: '1234567890'
})

{
  "message": "Account was created.",
  "authy_id": 111111111,
  "success": true
}

Start device registration

await authy.startRegistration({
   authy_id: 111111111,
   // via: 'push',
   // via: 'call',
   via: 'sms',

   // Not sure why, but works better with this. 🤷
   signature: crypto.randomBytes(32).toString('hex')
})

{
  "message": "PIN was sent via text-message. Please allow at least 1 minute for the text to arrive.",
  "request_id": "63c5e5d37e48672bc558405f",
  "approval_pin": 42,
  "provider": null,
  "success": true
}

Complete device registration

await authy.completeRegistration({
   authy_id: 111111111,
   pin: 133769
})

{
  "device": {
    "id": 222222222,
    "secret_seed": "b26ef78813a1f8600da7e9b4d5f62011",
    "api_key": "c93266f4d93902b89c998ce74163ea98",
    "reinstall": false
  },
  "authy_id": 111111111
}

List devices

await authy.listDevices({
   authy_id: 111111111,
   device_id: 222222222,
   ...authy.getOtps('b26ef78813a1f8600da7e9b4d5f62011')
})

{
  "message": "Devices List",
  "devices": [
    {
      "master_token_id": 333333333,
      "name": "Chrome",
      "registration_city": "Montcuq",
      "registration_country": "France",
      "user_agent": "Mozilla/5.0 (X11; OpenBSD amd64; rv:42.0) Gecko/1337 Firefox/69.0"
    }
  ]
}

There's more fields in there, just quoted those for example.

Delete a device

await authy.deleteDevice({
   authy_id: 111111111,
   delete_device_id: 333333333,
   device_id: 222222222,
   ...authy.getOtps('b26ef78813a1f8600da7e9b4d5f62011')
})

{
  "message": "The device was deleted",
  "success": true
}

Enable multi-device

await authy.enableMultiDevice({
   authy_id: 111111111,
   device_id: 222222222,
   ...authy.getOtps('b26ef78813a1f8600da7e9b4d5f62011')
})

{
  "message": "Settings changed.",
  "success": true
}

Disable multi-device

await authy.disableMultiDevice({
   authy_id: 111111111,
   device_id: 222222222,
   ...authy.getOtps('b26ef78813a1f8600da7e9b4d5f62011')
})

{
  "message": "Settings changed.",
  "success": true
}

Sync

await authy.sync({
   authy_id: 111111111,
   device_id: 222222222,
   ...authy.getOtps('b26ef78813a1f8600da7e9b4d5f62011')
})

{
  "message": "App Sync.",
  "apps": [
    {
      "name": "SendGrid",
      "authy_id": 444444444,
      "secret_seed": "8fcc63651386dcb2ac18c0095fa61704",
      "digits": 7
    }
  ],
  "deleted": [],
  "success": true
}

There's more fields in there, just quoted those for example.

Difference with authy-client

authy-client is a client for the official Authy API, for services to provide 2FA to their users through Authy.

In contrast, Authy User Client is meant to be used by the users themselves, to manage their Authy account from the CLI, without having to install any of the Authy apps, in a way that opens all the data and makes it easy to use the Authy secrets with any standard TOTP provider or password manager with TOTP support.

Alternatives

See also the equivalent Go version if that's more your jam. 🍓

See also

You don't want to use Authy, and actually, you don't even want to use a TOTP app. The only app you want is the password manager that you already use.

But sadly your password manager don't support TOTP natively, or it's a paid feature and you would like to stay on the free plan?

I gotcha. TOTP with a password manager that doesn't support TOTP 😅 is a small website I built that allows you to store TOTP secrets (with support for the QR code scanning dance) in a way that they'll be treated like a regular username and password from your password manager's perspective.

All you need to do is head to totp.vercel.app and let your password manager autocomplete the "user" (app) of your choice, and it'll generate a code for you. Everything client-side, the secrets never leave your password manager or your browser!

Debugging

Set DEBUG=authy-user-client in your environment to see all the requests and responses made by this program.