Authy Users

1
# Download the helper library from https://github.com/twilio/authy-python
2
from authy.api import AuthyApiClient
3

4
# Your API key from twilio.com/console/authy/applications
5
# DANGER! This is insecure. See http://twil.io/secure
6
authy_api = AuthyApiClient('api_key')
7

8
user = authy_api.users.create(
9
    email='new_user@example.com',
10
    phone='405-342-5699',
11
    country_code=57)
12

13
if user.ok():
14
    print user.id
15
    # user.id is the `authy_id` needed for future requests
16
else:
17
	print user.errors()

1
{
2
  "message": "User created successfully.",
3
  "user": {
4
    "id": 123
5
  },
6
  "success": true
7
}

A user may have multiple email addresses but only one phone is associated with each authy_id. Two separate API calls to register a user with the same device and different emails will return the same authy_id and store both emails for that user.

POST https://api.authy.com/protected/{FORMAT}/users/new

Email and phone number must be valid for the request to succeed. An invalid request will produce the following error response:

1
{
2
  "message": "User was not valid",
3
  "success": false,
4
  "errors": {
5
    "email": "is invalid",
6
    "message": "User was not valid"
7
  },
8
  "email": "is invalid",
9
  "error_code": "60027"
10
}

The send_install_link_via_sms parameter will override behavior set in the console. Check your application's settings. Note: the parameter is ignored and no install link will be sent if the user has synced a device with the Authy servers in the previous 90 days. You can see last_sync_date for a user's devices via the User Status endpoint.

If you want to send an install link regardless, we recommend using Twilio Programmable SMS (note: requires a Twilio Phone Number). Include the URL https://authy.com/download/ which will autodetect the device type and redirect the user to the appropriate download link. See the SMS docs for more information.

Enrolling a user (if you use the same phone number they used to sign up for the Authy App) automatically adds your application to their Authy App. You do not need to do any additional work to support TOTP tokens in the Authy app. To support additional Authenticator apps, like Google Authenticator, display a QR code to your users that contain a compatible TOTP secret. The API will return a link to a valid QR code. Instructions for generating that QR code are in the One-Time Passcodes reference documentation.

You might not have the email and the phone number of the user, or if you do, you might not want to share it with Twilio for compliance reasons.

For those cases you can use our Authy App based onboarding flow. The end user must have the Authy App installed and registered, meaning the end user has already provided their phone number and email to us.

1
// Example Payload
2
{
3
  "iss": "My Authy App",
4
  "iat": 1554395479,
5
  "exp": 1554395879,
6
  "context": {
7
    "custom_user_id": "3YgAIZklGPHmwpJfIC0PDy0E7l763OF3BHZo1p2xKhY",
8
    "authy_app_id": "1111111"
9
  }
10
}
11

12
// Example Header
13
{
14
  "alg": "HS256",
15
  "typ": "JWT"
16
}

1
// JWT signed with key 'obK3KxxxxxxxxxxxxxxxxxxxxC'
2
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJNeSBBdXRoeSBBcHAiLCJpYXQiOjE1NTQzOTU0NzksImV4cCI6MTU1NDM5NTg3OSwiY29udGV4dCI6eyJjdXN0b21fdXNlcl9pZCI6IjNZZ0FJWmtsR1BIbXdwSmZJQzBQRHkwRTdsNzYzT0YzQkhabzFwMnhLaFkiLCJhdXRoeV9hcHBfaWQiOiIxMTExMTExIn19.6pBOX0UL7jTmrudWGsJjT07GD8DlAP6uVlpHVZwJPTs"

First, create a JWT. The token will be used to tie the end user's Authy ID to your application. The token must:

1. Follow RFC 7519.
2. Be signed with your application's Production API Key found in the Twilio console.
3. Contain the following:

HS256 is the only algorithm supported.

1
{
2
  "alg": "HS256",
3
  "typ": "JWT"
4
}

During development, you can validate your JWT using https://jwt.io/. The example can be found here.

Next, create a QR string with the following format:

authy://account?token={JWT}

Note: we do not recommend storing the QR code since it can potentially leak sensitive data. Instead, we recommend:

1. Sending the QR code as a base64 encoded image in your HTML
2. Generating the QR code from your application with a library like github.com/skip2/go-qrcode. For testing, you can use an online generator like https://www.qr-code-generator.com/.

After the QR code is generated display it so your user can scan it with the Authy App.

After the end user scans the QR code there are two ways to get the user's Authy ID (required for subsequent verification challenges).

1. Poll registration status
2. Subscribe to a registration webhook

GET https://api.authy.com/protected/{FORMAT}/registrations/status?custom_user_id={CUSTOM_USER_ID}

URL

You can subscribe to a webhook that will notify you in real time when the registration is successful or not.

The payload for event user_registration_completed:

1
  "method": "POST",
2
  "params": {
3
    "events": [
4
      {
5
        "event": "user_registration_completed",
6
        "time": "2019-04-09T22:26:10.503Z",
7
        "objects": {
8
          "app": {
9
            "b_custom_code_allowed": false,
10
            "b_custom_message_allowed": false,
11
            "s_account_sid": "AC5f123456eabfa99ee3441ef1e84ad528",
12
            "s_device_app": null,
13
            "s_errors": "",
14
            "s_id": "54321",
15
            "s_name": "Application Name",
16
            "s_type": null
17
          },
18
          "registration": {
19
            "s_app_id": 54321,
20
            "s_authy_id": 123456,
21
            "s_custom_id": "885de433faedf8475426f11baeee2424f88fd935"
22
          },
23
          "user": {
24
            "as_authy_ids": [
25
              "123456"
26
            ],
27
            "b_banned": false,
28
            "s_authy_id": "123456",
29
            "s_country_code": "57",
30
            "s_errors": "",
31
            "s_locale": "en",
32
            "s_phone_number": "953a0fd8c9ec2a9f16a5ce58183cfa03"
33
          }
34
        },
35
        "request": {
36
          "id": "413fd53c-09af-43d6-8390-c346de8ccf0c",
37
          "ip": "IPv4_99a65f1a9e58fe49150aed5a188459b9b0b47157"
38
        },
39
        "public": true
40
      }
41
    ],
42
    "webhook_id": "WH_50087ea9-9568-4839-9191-b43908a4abd4"
43
  },
44
  "url": "https://example.io/webhook"
45
}

The payload for event user_registration_failed:

1
{
2
  "method": "POST",
3
  "params": {
4
    "events": [
5
      {
6
        "event": "user_registration_failed",
7
        "time": "2019-04-09T22:26:10.503Z",
8
        "objects": {
9
          "app": {
10
            "b_custom_code_allowed": false,
11
            "b_custom_message_allowed": false,
12
            "s_account_sid": "AC5f586933eabfa99ee3441ef1e84ad528",
13
            "s_device_app": null,
14
            "s_errors": "",
15
            "s_id": "54321",
16
            "s_name": "Application Name",
17
            "s_type": null
18
          },
19
          "error": {
20
            "s_code": "60000"
21
          }
22
        },
23
        "request": {
24
          "id": "413fd53c-09af-43d6-8390-c346de8ccf0c",
25
          "ip": "IPv4_99a65f1a9e58fe49150aed5a188459b9b0b47157"
26
        },
27
        "public": true
28
      }
29
    ],
30
    "webhook_id": "WH_50087ea9-9568-4839-9191-b43908a4abd4"
31
  },
32
  "url": "https://example.io/webhook"
33
}

1
# Download the helper library from https://github.com/twilio/authy-python
2
from authy.api import AuthyApiClient
3

4
# Your API key from twilio.com/console/authy/applications
5
# DANGER! This is insecure. See http://twil.io/secure
6
authy_api = AuthyApiClient('api_key')
7

8
status = authy_api.users.status(authy_id)
9

10
if status.ok():
11
	print(status.content)

1
{
2
  "status": {
3
    "authy_id": 123,
4
    "confirmed": true,
5
    "registered": true,
6
    "country_code": 1,
7
    "phone_number": "XXX-XXX-1111",
8
    "email": "user@domain.com",
9
    "devices": [
10
      "desktop",
11
      "iphone"
12
    ],
13
    "has_hard_token": false,
14
    "account_disabled": false,
15
    "detailed_devices": [
16
      {
17
        "creation_date": 1540576334,
18
        "device_id": 123123,
19
        "device_type": "authy",
20
        "last_sync_date": 1540576768,
21
        "os_type": "desktop",
22
        "registration_device_id": null,
23
        "registration_method": "sms",
24
        "enabled_unlock_methods": "",
25
        "last_unlock_method_used": "unknown",
26
        "last_unlock_date": "unknown"
27
      },
28
      {
29
        "creation_date": 1540594738,
30
        "device_id": 456456,
31
        "device_type": "authy",
32
        "last_sync_date": 1540601752,
33
        "os_type": "ios",
34
        "registration_device_id": null,
35
        "registration_method": "sms",
36
        "enabled_unlock_methods": "pin, fingerprint",
37
        "last_unlock_method_used": "pin",
38
        "last_unlock_date": 1540601752
39
      }
40
    ],
41
    "deleted_devices": [
42
      {
43
        "creation_date": 1540481558,
44
        "deletion_date": 1540481571,
45
        "device_id": 789789,
46
        "device_type": "authy",
47
        "last_sync_date": 1540481560,
48
        "os_type": "desktop",
49
        "registration_device_id": 123123,
50
        "registration_method": "push"
51
      }
52
    ],
53
  },
54
  "message": "User status.",
55
  "success": true
56
}

Once a user is created and registered with your application, you can request information on that user from Twilio. Using the User status call, you will receive:

Determine which end-user apps to trust for authentication. Our API records uniquely identifiable numbers for every installed app, as well as the sequence of app installs and the methods of installation. More information in our blog post: Authy trust-chain for added devices.

Information returned in the detailed_device section of the user status endpoint includes:

• registration_method: how the device was added (sms, call, push).

• last_sync_date: Unix timestamp of last time the device was synced with Authy servers.

• registration_device_id: device ID of the approving device if registration_method is push. New as of 2019-06-15, devices added before this date will be null. See Authy trust-chain for added devices for more information

• enabled_unlock_methods: one or more of pin, faceid, fingerprint, password, none, unknown. Refers to the unlock method for the entire app, not just the settings page.

  • Only available for iOS app version 22.8+, Android app version 23.9.3+, and Desktop app version v1.8.0+
  • Not available for Chrome app
  • If an unlock method is enabled for iOS app, the linked Apple Watch app will still display non-transactional TOTP codes without requiring an unlock, but it will not allow a user to accept a push request.

• last_unlock_method: enabled method last used.

• last_unlock_date: Unix timestamp of last time the device was unlocked.

GET https://api.authy.com/protected/{FORMAT}/users/{AUTHY_ID}/status

1
# Download the helper library from https://github.com/twilio/authy-python
2
from authy.api import AuthyApiClient
3

4
# Your API key from twilio.com/console/authy/applications
5
# DANGER! This is insecure. See http://twil.io/secure
6
authy_api = AuthyApiClient('api_key')
7

8
deleted = authy_api.users.delete(authy_id)
9

10
if deleted.ok():
11
    print deleted.content

1
{
2
  "message": "User removed from application",
3
  "success": true
4
}

If you want to remove a user from your application you can use the Remove API. Note: removing a user will immediately disable token verifications.

Best practice is to remove a user if they disable Two-factor Authentication or remove an account with your App. If you accidentally remove a user, you can recover users through the Console - but we suggest that you instead go through your registration flow again.

curl -X POST https://api.authy.com/protected/{FORMAT}/users/{USER ID}/remove -H "X-Authy-API-Key: {KEY}"