Authy Users

Before you can secure a user with the Twilio Authy API, you need to create a user. The API requires you set an email, phone number and country code for each user.

When a user is first created, you will receive an authyid which you must then store with the user's profile in your own database. Do not lose this ID - you will use it every time you wish to authenticate a user!

Your users can change their phone number registered with the API without your knowledge by using the Authy Mobile or Desktop Application. They may also use the Authy.com phone change security review. You can get webhooks of when this phone number changes via our Webhooks API

Add a User

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?api_key={KEY}

Parameters

Name Type Description
send_install_link_via_sms Boolean (optional) Value to enable or disable the initial text message. Default=TRUE. Can be set from the Dashboard.
user[email] String (required) More than one email can be stored per AuthyID, but only the initially created email will display in the Dashboard until it is removed.
user[cellphone] String (required) Foreign key for the AuthyID (the AuthyID will be the primary key going forward).
user[country_code] String (required) Numeric calling country code of the country Eg: 1 for the US. 91 for India. 54 for Mexico. See: Country code list dropdown

Response

Name Type Description
user User This is the AuthyID of the created user.

Example

NOTE: You can use dashes, periods, spaces or nothing to separate parts of the cell phone number.

curl "http://api.authy.com/protected/json/users/new" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
-d user[email]="user@domain.com" \
-d user[cellphone]="317-338-9302" \
-d user[country_code]="54"

Sample response

{
    "user": {
        "id":2
    }
}

Request with errors

curl "http://api.authy.com/protected/json/users/new" \
-H "X-Authy-API-Key: d57d919d11e6b221c9bf6f7c882028f9" \
-d user[email]="user.com" \
-d user[cellphone]="AAA-338-9302" \
-d user[country_code]="1"

Sample response

{
    "errors": {
        "email":"is invalid",
        "cellphone":"must be a valid cellphone number."
    }
}


Request User Status

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:

  1. country_code
  2. phone number: last 4 digits of phone number.
  3. devices: List of devices, options are: android, android_tablet, ios, iphone, iphone_sdk, chrome, authy_chrome, sms, android_sdk
  4. registered: true when the Authy Mobile/Desktop App was registered.
  5. confirmed: true when the user has used a valid code before.
GET http://api.authy.com/protected/{FORMAT}/users/{USER ID}/status?api_key={KEY}

Parameters

Name Type Description
user_ip String IP of the user requesting to see the application details. Optional.

Response

Name Type Description
status Dictionary Status contains information about the user.
message String A message indicating the result of the operation.
success Boolean True if the request was successful.

Example

{
    "status": {
        "authy_id":2,
        "confirmed":true,
        "registered":true,
        "country_code":1,
        "phone_number":"XXX-XXX-9302",
        "devices": [
            "authy_chrome",
            "android"
        ]
    },
    "message":"User status.",
    "success":true
}


Remove a User

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 he or she disables Two-factor Authentication or removes 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}"

Parameters

Name Type Description
user_ip String (optional) The ip requesting to remove the user

Response

Name Type Description
success Boolean True if the user was scheduled for deletion.
message String A messaging indicating the result of the operation.

Example

{
    "message": "User removed from application",
    "success": true
}

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.