Menu

Expand
Rate this page:

Authy Dashboard API

For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience and new features including:

  • Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, PHP, and Golang
  • Access via the Twilio CLI
  • Improved Visibility and Insights
  • Push authentication SDK embeddable in your own application

You are currently viewing the Authy API. New features and development will be on the Verify API. Check out the FAQ for more information and the migrating to Verify guide to get started.

The Authy Dashboard API is a way to manage and view configuration, stats, and more for your Authy Applications. Features of this API are also available via the Twilio Authy console.

Return codes

The following are the return codes supported by the Dashboard API.

200: Request was successful.

400: When the Request was invalid.

404: When the resource was not found.

500: Internal server error.

Error codes

When the API returns a status other than 200, we add an error code in the message body. For further information, please check the error codes page for a complete list of possible errors.

Supported Formats

At the moment we support JSON and XML formats.

For convenience and compatibility with old http implementations we only support the POST and GET http verbs.

Signing Requests

Most of the end points listed in this document require a signature. Please follow the next steps to successfully sign the request:

1. Create a string variable using the url without params:
url = "https://api.authy.com/dashboard/application/access_keys"
2. Create a string variable with the HTTP method in upper case (GET, POST):
http_method = "GET"
3. Sort the list of parameters in case-sensitive order and convert them to URL format:

Both key and value should be URL-encoded.

params = {b: "val|ue&2", a: "value1"}
sorted_params = "a=value1&b=val%7Cue%262"
4. Generate a unique nonce

Your language of choice likely has a nonce generator library, such nonce in Node.js.

nonce = "1427849783.886085"
5. Join nonce, http_method, url and params_in_url_format together with the | character:

Note: the string should contain exactly 3 | characters.

data = nonce + "|" + http_method + "|" + url + "|" + params_in_url_format
"1427849783.886085|POST|https://api.authy.com/dashboard/json/application/webhooks|a=value1&b=val%7Cue%262"
6. Hash the resulting data using HMAC-SHA256, using your api_signing_key as the key:

Get your API signing key from "Webhooks API Keys" section of the application settings tab in the Twilio Console.

digest = hmac_sha256(data, api_signing_key)
7. Base64 encode the digest:

Base64 encoding should not contain line feeds. It must be encoded as described in the RFC 4648.

digest_in_base64 = encode_in_base64(digest)
8. Make the HTTP request with specified headers

Send the digest_in_base64 in the X-Authy-Signature header

Send the nonce in the X-Authy-Signature-Nonce header.

request.headers["X-Authy-Signature"] = digest_in_base64
request.headers["X-Authy-Signature-Nonce"] = nonce make_request(request)

Objects

User

End User registered in your application.

Attributes

Name Type Description
authy_id Integer User identifier.
used_at Datetime The last date the user entered a valid code.
confirmed Boolean True if the user has confirmed the phone number.
country_code Integer Country code of the user.
cellphone Integer Phone number of the user.
email String User email.
last_sync_at Datetime The last date the user synced his Authy App.
suspended Boolean True if the user account is suspended.
sms_enabled Boolean True if the user will be able to receive authentication codes via text message (SMS).
calls_enabled Boolean True if the user will be able to receive authentication codes via phone call.
status String User status in the application. active, inactive, suspended, blocked, or removed.
removal_date Datetime Returned when the user was removed from the application.

Application

Your Application.

Attributes

Name Type Description
app_id Integer Serial id of the application
api_key String Public api key of the application
app_api_key String Admin api key of the application
name String Name of the application
created_at Time The date when the application was created.
version Integer Version of the application
users_count Integer Users count
hard_tokens_enabled Boolean True if the application supports hardware tokens
suspended Boolean True if the application is suspended
uses_voice_recording Boolean True if the application has custom voice recordings
twilio_account_sid String Twilio account id tied to the application

API Settings

API Settings of the Application.

Attributes

Name Type Description
welcome_message_enabled Boolean If true a welcome message will be sent to the user when he/she is registered with Authy. True by default.
force_sms Boolean If true the request SMS end point will always try to send the message. False by default.
force_call Boolean If true the request Call end point will always try to start the phone call. False by default.
force_verification Boolean If true the user tokens are always verified even if he/she hasn’t confirmed his/her phone number. True by default.
sms_enabled Boolean True when the application has text messages enabled. True by default.
calls_enabled Boolean True when the application has phone calls enabled. True by default.
call_requires_input Boolean When true the phone calls asks the user to press 1 before reading the security code. True by default.
otp_length Integer Within 6 and 8. Length of the OTP code for your application.
onetouch_callback_url String The url for the OneTouch callback if any.
onetouch_callback_method String The http method used by the OneTouch call back (post | get) if any.
allow_custom_messages Boolean True if custom messages are allowed for your application when sending SMS for OTP or Phone Verification.
tts_app_name String Specify a phonetic spelling Text-to-speech (TTS) for your application name when delivering a code via phone call.
sdk_push_apn_enabled Boolean True when push credentials for iOS have been uploaded to let Authy manage push notifications for the TwilioAuth SDK.
sdk_push_gcm_enabled Boolean True when push credentials for Android have been uploaded to let Authy manage push notifications for the TwilioAuth SDK.
push_send_to_authy Boolean When False, OneTouch requests will not be visible in the Authy app.
push_send_to_sdk Boolean When False, Twilio will not send OneTouch push notifications to your app, but you can still deliver OneTouch requests and show them in your app.

UI Settings

UI Settings of the Application.

Attributes

Name Type Description
custom_assets Boolean True when the application has custom assets.
timer_color Hex Color Color of the timer
circle_color Hex Color Color of the circle timer
circle_background Hex Color Color of the circle background.
background_color Hex Color Background color
labels_color Hex Color Labels color
labels_shadow_color Hex Color Labels shadow color
token_color Hex Color Color of the security code

Access Key

Key to access the dashboard API.

Attributes

Name Type Description
_id String Id of the access key
value String 32 bytes access key (protected)
user_id Integer Id of the user
status String Status of the access key. options: active, pending, suspended

Stats

Stats of your Application.

Attributes

Name Type Description
month String Month and year formatted like this: ""
api_calls_count Integer Number of requests performed on the API.
users_count Integer Users count
auths_count Integer Authentications count
sms_count Integer Text Messages requested.
calls_count Integer Phone calls requested.
request_phone_info_count Integer Number of phone info requests.
sms_verification_count Integer Number of SMS verifications.
call_verification_count Integer Number of phone calls verifications.
check_verification_count Integer Number of phones verified.

Activity

User activities.

Attributes

Name Type Description
created_at Time The date when the activity was created.
action_name String Name of the action. The supported actions are: verify_token, request_sms and request_call.
user_email String Email of the user that performed the activity.
user_phone String Phone of the user that performed the activity.

Device

User Device like iPhone, Android, iPad.

Attributes

Name Type Description
name String The name of the device. Default name is "Default".
device_type String The type of the device. The value is either: "sms", "android", "android_tablet", "ipad", "ipod", "iphone", "authy_chrome" or "unknown"
needs_health_check Boolean Whether the Device requires health check or not.
country String Geolocalization's country. This can be empty.
region String Geolocalization's region. This can be empty.
city String Geolocalization's city. This can be empty.
registered Boolean Whether the Device is registered or not.
token Token The token information.

Token

Token information associated to the Device.

Attributes

Name Type Description
created_at Time The date when the token was created.
locked Boolean Whether the token is locked. This means the token was confirmed by the user.
last_health_check_result Boolean Whether the health check was successful or not.
health_checked_at Time The date when the token was checked.

Create Application

To start using the Dashboard API you first need to create an Application (if you don't have one yet) using this end-point.
It'll return you the app_api_key once and you should store it in your database since there's no way to get it later.

It'll also return the access key for the owner of the Application.
The application api key and the access key are needed to access the rest of the dashboard API end-points.

This end point doesn't require to sign the request.

POST /dashboard/:format/applications

Parameters

Name Type Description
name String The name of the new Application.
integration_api_key String Integration API key. Please contact sales@authy.com to get one.
email String The email of the user that's creating the application.
country_code Integer The country code of the user that's creating the application.
phone_number String The phone number of the user that's creating the application.

Response

Name Type Description
app_api_key String API key to access the rest of the dashboard API.
api_signing_key String Key to sign the requests.
access_key String Access key of the owner User
app_id Integer Serial id of the application.

Example

Creating new Application called "My New App"

curl -d name="My New App" \
     -d phone_number="650-345-2233" \
     -d country_code=1 \
     -d email="sample@authy.com" \
     -d integration_api_key="2b132d1ec7707a5c74e42427e996b848" \
     "https://api.authy.com/dashboard/json/applications"

Sample response

{
  "app_api_key": "b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339",
  "api_signing_key": "3xhQiaC87dlUdOGbCmCeMYSBhtUt4vtc2DaCqI1WGBvhJo",
  "access_key": "d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f",
  "api_key": "16e8a9f4ccc6982ab2b79f5d470f384a",
  "app_id": 13234,
  "name": "My New App",
}

Listing applications

Endpoint to list all applications.
This end point doesn't require a signature.

GET /dashboard/:format/applications

Parameters

Name Type Description
integration_api_key String Integration API key. Please contact sales@authy.com to get one.
include_current_stats String "true" or "false". When "true", response will include for each application "current_stats" attribute with Stats Objects of the current month.

Response

Name Type Description
applications Array List of application objects.

Example

Listing all applications associated with the integration.

curl "https://api.authy.com/dashboard/json/applications?integration_api_key=2b132d1ec7707a5c74e42427e996b848"

Sample response

{
  "applications": [
    {
      "app_id": 13234,
      "api_key": "public_api_key",
      "app_api_key": "application_admin_api_key",
      "name": "Dashboard Test",
      "version": 8,
      "users_count": 1324,
      "hard_tokens_enabled": false,
      "suspended": false,
      "uses_voice_recording": false,
      "twilio_account_sid": "twilio_account_id"
    }
  ],
  "count": 1
}

This method doesn't require to sign the request.

Create Access Keys For Your Staff

This end-point is used by the admin user to add new access keys with defined privileges.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins

POST /dashboard/:format/application/access_keys

Parameters

Name Type Description
app_api_key String API key to access the rest of the dashboard API.
access_key String Admin access key
role String Role of the access key, options: admin, collaborator, support
email String Email of the user associated to the new access key.
country_code Integer Country code of the user associated to the new access key.
phone_number String Phone number of the user associated to the new access key.

Response

Name Type Description
_id String Id of the access key
value String 32 bytes access key (protected)
user_id Integer Id of the user
status String Status of the access key. options: active, pending, suspended

Example

Adding new support access key for user 23.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     -d role="support" \
     -d user_id="23" \
     "https://api.authy.com/dashboard/json/application/access_keys"

Sample response

{
  "_id": "5081e6facaa71df429000002",
  "value": "02dc1efe84b1409382fd901f8b6dfd430cc9369d7e8fb0994b42aee2db2c388d",
  "user_id": 20,
  "status": "active"
}

Listing Access Keys

This end-point is used to see the list of access keys associated with the Application.
NOTE: this end-point won’t actually return the key to access the api. Basically this is used to get the id and status of the access keys.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins and collaborators

GET /dashboard/:format/application/access_keys

Parameters

Name Type Description
app_api_key String API key to access the rest of the dashboard API.
access_key String Admin access key.

Response

Name Type Description
access_keys Array List of Access Key objects

Example

Listing all access keys.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/access_keys?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "access_keys": [
    {
      "_id": "5081e6facaa71df429000002",
      "user_id": 20,
      "status": "active"
    }
  ],
  "count": 1
}

Getting a single Access Key

This end-point is used to see a single access key associated with the Application.
NOTE: this end-point won’t actually return the key to access the api. Basically this is used to get the id and status of the access key.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins and collaborators

GET /dashboard/:format/application/access_keys/:id

Parameters

Name Type Description
app_api_key String API key to access the rest of the dashboard API.
access_key String Admin access key.
id String Access key id.

Response

Name Type Description
_id String Id of the access key
value String 32 bytes access key (protected)
user_id Integer Id of the user
status String Status of the access key. options: active, pending, suspended

Example

Get access key.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/access_keys/5081e6facaa71df429000002?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "_id": "5081e6facaa71df429000002",
  "user_id": 20,
  "status": "active"
}

Suspending Access Keys

Used to suspend access keys preventing them from accessing the dashboard API.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins

POST /dashboard/:format/application/access_keys/:id/suspend

Parameters

Name Type Description
app_api_key String API key to access the rest of the dashboard API.
access_key String Admin access key.
id String Access key id.

Response

Name Type Description
_id String Id of the access key
value String 32 bytes access key (protected)
user_id Integer Id of the user
status String Status of the access key. options: active, pending, suspended

Example

Suspending support access key of user 23

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/access_keys/5081e6facaa71df429000002/suspend"

Sample response

{
  "_id": "5081e6facaa71df429000002",
  "user_id": 20,
  "status": "suspended"
}

Unsuspending Access Keys

Used to unsuspend access keys allowing them access the API again.
You need to sign this request using the api_signing_key as described in the Signing Requests section.


Accessible by: admins

POST /dashboard/:format/application/access_keys/:id/unsuspend

Parameters

Name Type Description
app_api_key String API key to access the rest of the dashboard API.
access_key String Admin access key.

Response

Name Type Description
_id String Id of the access key
value String 32 bytes access key (protected)
user_id Integer Id of the user
status String Status of the access key. options: active, pending, suspended

Example

Suspending support access key of user 23

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/access_keys/5081e6facaa71df429000002/unsuspend"

Sample response

{
  "_id": "5081e6facaa71df429000002",
  "user_id": 20,
  "status": "active"
}

Deleting Access Keys

Used to delete access keys (i.e. disallowing to access the API again).
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins

POST /dashboard/:format/application/access_keys/:id/delete

Parameters

Name Type Description
app_api_key String API key to access the rest of the dashboard API.
access_key String Admin access key.
id String Access key id to be deleted.

Response

Name Type Description
deleted Boolean True when the access key was deleted.

Example

Deleting support access key of user 23

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/access_keys/5081e6facaa71df429000002/delete"

Sample response

{
  "deleted": true
}

Update Application Details

Update application general details like name and billing info.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins and collaborators

POST /dashboard/:format/application/update

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
name String Name of the application
billing_address String Billing address that appears in the invoice
billing_email String Billing email that appears in the invoice
billing_phone String Billing phone that appears in the invoice

Response

Name Type Description
app_id Integer Serial id of the application
api_key String Public api key of the application
app_api_key String Admin api key of the application
name String Name of the application
created_at Time The date when the application was created.
version Integer Version of the application
users_count Integer Users count
hard_tokens_enabled Boolean True if the application supports hardware tokens
suspended Boolean True if the application is suspended
uses_voice_recording Boolean True if the application has custom voice recordings
twilio_account_sid String Twilio account id tied to the application

Example

Updating name

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     -d name="New Dashboard Test" \
     "https://api.authy.com/dashboard/json/application/update"

Sample response

{
  "app_id": 13234,
  "api_key": "public_api_key",
  "app_api_key": "application_admin_api_key",
  "name": "New Dashboard Test",
  "version": 8,
  "users_count": 1324,
  "hard_tokens_enabled": false,
  "suspended": false,
  "uses_voice_recording": false,
  "twilio_account_sid": "twilio_account_id"
}

Get Application Details

Get application general details like name and billing info.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

GET /dashboard/:format/application/details

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
include_current_stats String "true" or "false". When "true", response will include for the application "current_stats" attribute with Stats Objects of the current month.
include_sensitive_data String "true" or "false". When "true" (default), response will include application api keys.

Response

Name Type Description
app_id Integer Serial id of the application
api_key String Public api key of the application
app_api_key String Admin api key of the application
name String Name of the application
created_at Time The date when the application was created.
version Integer Version of the application
users_count Integer Users count
hard_tokens_enabled Boolean True if the application supports hardware tokens
suspended Boolean True if the application is suspended
uses_voice_recording Boolean True if the application has custom voice recordings
twilio_account_sid String Twilio account id tied to the application

Example

Getting application details

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/details?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "app_id": 13234,
  "api_key": "public_api_key",
  "app_api_key": "application_admin_api_key",
  "name": "Dashboard Test",
  "version": 8,
  "users_count": 1324,
  "hard_tokens_enabled": false,
  "suspended": false,
  "uses_voice_recording": false,
  "twilio_account_sid": "twilio_account_id"
}

Get Application UI Settings

Get the current& UI Settings.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

GET /dashboard/:format/application/ui_settings

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
custom_assets Boolean True when the application has custom assets.
timer_color Hex Color Color of the timer
circle_color Hex Color Color of the circle timer
circle_background Hex Color Color of the circle background.
background_color Hex Color Background color
labels_color Hex Color Labels color
labels_shadow_color Hex Color Labels shadow color
token_color Hex Color Color of the security code

Example

Getting application UI settings

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/ui_settings?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "custom_assets": true,
  "timer_color": "#000000",
  "circle_color": "#000000",
  "circle_background": "#000000",
  "background_color": "#000000",
  "labels_color": "#000000",
  "labels_shadow_color": "#000000",
  "token_color": "#000000"
}

Update Application UI Settings

Update the current UI Settings. Once this is posted the mobile phone assets are automatically synced.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins and collaborators

POST /dashboard/:format/application/ui_settings/update

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
timer_color Hex Color Color of the timer
circle_color Hex Color Color of the circle timer
circle_background Hex Color Color of the circle background.
background_color Hex Color Background color
labels_color Hex Color Labels color
labels_shadow_color Hex Color Labels shadow color
token_color Hex Color Color of the security code

Response

Name Type Description
custom_assets Boolean True when the application has custom assets.
timer_color Hex Color Color of the timer
circle_color Hex Color Color of the circle timer
circle_background Hex Color Color of the circle background.
background_color Hex Color Background color
labels_color Hex Color Labels color
labels_shadow_color Hex Color Labels shadow color
token_color Hex Color Color of the security code

Example

Updating background_color to red

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     -d background_color="#ff0000" \
     "https://api.authy.com/dashboard/json/application/ui_settings/update"

Sample response

{
  "custom_assets": true,
  "timer_color": "#000000",
  "circle_color": "#000000",
  "circle_background": "#000000",
  "background_color": "#ff0000",
  "labels_color": "#000000",
  "labels_shadow_color": "#000000",
  "token_color": "#000000"
}

Update Application Logos

Updates the logos that are used in the mobile and desktop applications. Once this is posted the mobile phone assets are automatically synced.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

The data should be posted as a multipart form.

Accessible by: admins and collaborators

POST /dashboard/:format/application/assets/update

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
main_logo String Image data for the main logo. Supported formats: png. Maximum size: 588x214. No more than 128kb is accepted.
sidebar_logo String Image data for the sidebar logo. Supported formats: png. Image size: 81x81. No more than 128kb is accepted.

Response

Name Type Description
success Boolean Whether the request was successful or not.
original_assets Dictionary URLs to the original logo and sidebar logo.

Example

Updating background_color to red

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -F app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -F access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     -F main_logo="@/path/to/logo.png" \
     -F sidebar_logo="@/path/to/sidebar_logo.png" \
     "https://api.authy.com/dashboard/json/application/assets/update"

Sample response

{
  "original_assets": {
    "logo_url": "<url to the original logo>",
    "sidebar_url": "<url to the original sidebar logo>"
  },
  "success": true
}

Get Application Logos

Lists the logos that are used in the mobile and desktop applications. The response contains the original assets and the processed ones.

Accessible by: support, admins and collaborators

GET /dashboard/:format/application/assets

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
success Boolean true
assets Dictionary Includes the device, resolution and logos.
original_assets Dictionary Includes the url to the original logo and sidebar logo.

Example

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/assets"

Sample response

{
  "assets": {
    "android": {
      "med": {
        "logo_url": "<logo url>",
        "sidebar_url": "<logo url>"
      },
      "high": {
        "logo_url": "<logo url>",
        "sidebar_url": "<logo url>"
      },
      "extra_high": {
        "logo_url": "<logo url>",
        "sidebar_url": "<logo url>"
      }
    },
    "ios": {
      "med": {
        "logo_url": "<logo url>",
        "sidebar_url": "<logo url>"
      },
      "high": {
        "logo_url": "<logo url>",
        "sidebar_url": "<logo url>"
      },
      "extra_high": {
        "logo_url": "<logo url>",
        "sidebar_url": "<logo url>"
      }
    },
    ...
  },
  "original_assets": {
    "logo_url": "<url to the original logo>",
    "sidebar_url": "<url to the original sidebar logo>"
  },
  "success": true
}

Get Application Logos Status

Gets the status of the process generating the assets for recently uploaded logos. Status can be "processing" or "finished".

Accessible by: support, admins and collaborators

GET /dashboard/:format/application/assets/status

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
success Boolean True when the status is successfully retrieved.
status String Status of the process.
message String Description of the status.

Example

Updating background_color to red

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/assets/status"

Sample response

{
    "message": "Assets were processed",
    "status": "finished",
    "success": true
}

Get Application API Settings

Get the current API settings.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins and collaborators

GET /dashboard/:format/application/api_settings

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
welcome_message_enabled Boolean If true a welcome message will be sent to the user when he/she is registered with Authy. True by default.
force_sms Boolean If true the request SMS end point will always try to send the message. False by default.
force_call Boolean If true the request Call end point will always try to start the phone call. False by default.
force_verification Boolean If true the user tokens are always verified even if he/she hasn’t confirmed his/her phone number. True by default.
sms_enabled Boolean True when the application has text messages enabled. True by default.
calls_enabled Boolean True when the application has phone calls enabled. True by default.
call_requires_input Boolean When true the phone calls asks the user to press 1 before reading the security code. True by default.
otp_length Integer Within 6 and 8. Length of the OTP code for your application.
onetouch_callback_url String The url for the OneTouch callback if any.
onetouch_callback_method String The http method used by the OneTouch call back (post | get) if any.
allow_custom_messages Boolean True if custom messages are allowed for your application when sending SMS for OTP or Phone Verification.
tts_app_name String Specify a phonetic spelling Text-to-speech (TTS) for your application name when delivering a code via phone call.
sdk_push_apn_enabled Boolean True when push credentials for iOS have been uploaded to let Authy manage push notifications for the TwilioAuth SDK.
sdk_push_gcm_enabled Boolean True when push credentials for Android have been uploaded to let Authy manage push notifications for the TwilioAuth SDK.
push_send_to_authy Boolean When False, OneTouch requests will not be visible in the Authy app.
push_send_to_sdk Boolean When False, Twilio will not send OneTouch push notifications to your app, but you can still deliver OneTouch requests and show them in your app.

Example

Getting Application API settings

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/api_settings?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "welcome_message_enabled": true,
  "force_sms": false,
  "force_call": false,
  "force_verification": true,
  "sms_enabled": true,
  "calls_enabled": true,
  "call_requires_input": true
}

Update API Settings

Update the current API settings.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins and collaborators

POST /dashboard/:format/application/api_settings/update

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
force_sms Boolean If true the request SMS end point will always try to send the message. False by default.
force_call Boolean If true the request Call end point will always try to start the phone call. False by default.
force_verification Boolean If true the user tokens are always verified even if he/she hasn’t confirmed his/her phone number. True by default.
welcome_message_enabled Boolean If true a welcome message will be sent to the user when he/she is registered with Authy. True by default.
sms_enabled Boolean True when the application has text messages enabled. True by default.
calls_enabled Boolean True when the application has phone calls enabled. True by default.
call_requires_input Boolean When true the phone calls asks the user to press 1 before reading the security code. True by default.
otp_length Integer Within 6 and 8. Length of the OTP code for your application.
tts_app_name String Specify a phonetic spelling Text-to-speech (TTS) for your application name when delivering a code via phone call.
tts_app_name_enabled Boolean If true, tts_app_name will be used when delivering a code via phone call.
push_send_to_authy Boolean When False, OneTouch requests will not be visible in the Authy app.
push_send_to_sdk Boolean When False, Twilio will not send OneTouch push notifications to your app, but you can still deliver OneTouch requests and show them in your app.

Response

Name Type Description
welcome_message_enabled Boolean If true a welcome message will be sent to the user when he/she is registered with Authy. True by default.
force_sms Boolean If true the request SMS end point will always try to send the message. False by default.
force_call Boolean If true the request Call end point will always try to start the phone call. False by default.
force_verification Boolean If true the user tokens are always verified even if he/she hasn’t confirmed his/her phone number. True by default.
sms_enabled Boolean True when the application has text messages enabled. True by default.
calls_enabled Boolean True when the application has phone calls enabled. True by default.
call_requires_input Boolean When true the phone calls asks the user to press 1 before reading the security code. True by default.
otp_length Integer Within 6 and 8. Length of the OTP code for your application.
onetouch_callback_url String The url for the OneTouch callback if any.
onetouch_callback_method String The http method used by the OneTouch call back (post | get) if any.
allow_custom_messages Boolean True if custom messages are allowed for your application when sending SMS for OTP or Phone Verification.
tts_app_name String Specify a phonetic spelling Text-to-speech (TTS) for your application name when delivering a code via phone call.
sdk_push_apn_enabled Boolean True when push credentials for iOS have been uploaded to let Authy manage push notifications for the TwilioAuth SDK.
sdk_push_gcm_enabled Boolean True when push credentials for Android have been uploaded to let Authy manage push notifications for the TwilioAuth SDK.
push_send_to_authy Boolean When False, OneTouch requests will not be visible in the Authy app.
push_send_to_sdk Boolean When False, Twilio will not send OneTouch push notifications to your app, but you can still deliver OneTouch requests and show them in your app.

Example

Disabling welcome message

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     -d welcome_message_enabled="false" \
     "https://api.authy.com/dashboard/json/application/api_settings/update"

Sample response

{
  "welcome_message_enabled": false,
  "force_sms": false,
  "force_call": false,
  "force_verification": true,
  "sms_enabled": true,
  "calls_enabled": true,
  "call_requires_input": true
}

Delete Application

Deletes the Application associated with the application api key. The Application can only be deleted if it doesn't have pending invoices and it doesn't have users.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins

POST /dashboard/:format/application/delete

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
integration_api_key String Integration API key.

Response

Name Type Description
deleted Boolean True when the application was deleted.

Example

Deleting an application

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/delete"

Sample response

{
  "deleted": true
}

Suspend Application

Suspends the Application associated with the application api key.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins

POST /dashboard/:format/application/suspend

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
suspended Boolean True when the application was suspended.
curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/suspend"

Sample response

{
  "suspended": true
}

Unsuspend Application

Unsuspends the Application associated with the application api key.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins

POST /dashboard/:format/application/unsuspend

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
suspended Boolean False when the application is not suspended.

Example

Suspending an application

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/unsuspend"

Sample response

{
  "suspended": false
}

Get Application Stats

Get the Application stats for the last 12 months.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins and collaborators

GET /dashboard/:format/application/stats

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
year Integer Filter Stats Objects by year.
month Integer Within 1 and 12. Filter Stats Objects by month. Use it along with year.

Response

Name Type Description
stats Array List of Stats Objects

Example

Getting Application stats.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/stats?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "stats": [
    {
      "month": "082013",
      "api_calls_count": 100,
      "users_count": 40,
      "auths_count": 1000,
      "sms_count": 20,
      "calls_count": 28,
      "request_phone_info_count": 0,
      "sms_verification_count": 0,
      "call_verification_count": 0,
      "check_verification_count": 0
    }
  ],
  "count": 1
}

List Users

Get the lists of registered users.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

GET /dashboard/:format/application/users

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
page Integer The page to display
per_page Integer The amount of users to display per page (maximum 50)
q String Optional query to search users by email or phone number.
status String Option status to filter the users by status. Available options are: confirmed, removed, all and suspended. Removed users only will be returned when filtering by removed.
phone_number_mask_level String Optional string within "min", "med", or "max" level to obfuscate the users's phone number.

Response

Name Type Description
users Array List of User objects

Example

Getting Application users.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/users?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f&
     phone_number_mask_level=min"

Sample response:

{
  "users": [
    {
      "authy_id": 23,
      "used_at": "2013-08-18 21:10:43 UTC",
      "confirmed": true,
      "country_code": 1,
      "cellphone": "650-XXX-9822",
      "email": "sample@authy.com",
      "last_sync_at": "2013-08-18 21:08:25 UTC",
      "suspended": false,
      "sms_enabled": true,
      "status": "active",
      "calls_enabled": true,
      "removal_date": null          
    }
  ],
  "count": 1,
  "total_count": 1
}

Get User Details

Get the details of a specific user.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

GET /dashboard/:format/application/users/:id

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
phone_number_mask_level String Optional string within "min", "med", or "max" level to obfuscate the users's phone number.

Response

Name Type Description
authy_id Integer User identifier.
used_at Datetime The last date the user entered a valid code.
confirmed Boolean True if the user has confirmed the phone number.
country_code Integer Country code of the user.
cellphone Integer Phone number of the user.
email String User email.
last_sync_at Datetime The last date the user synced his Authy App.
suspended Boolean True if the user account is suspended.
sms_enabled Boolean True if the user will be able to receive authentication codes via text message (SMS).
calls_enabled Boolean True if the user will be able to receive authentication codes via phone call.
status String User status in the application. active, inactive, suspended, blocked, or removed.
removal_date Datetime Returned when the user was removed from the application.

Example

Getting User details.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/users/23?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "authy_id": 23,
  "used_at": "2013-08-18 21:10:43 UTC",
  "confirmed": true,
  "country_code": 1,
  "cellphone": "650-344-9822",
  "email": "sample@authy.com",
  "last_sync_at": "2013-08-18 21:08:25 UTC",
  "suspended": false
  "suspended": false,
  "sms_enabled": true,
  "status": "active",
  "calls_enabled": true,
  "removal_date": null          
}

Get User Logs

Get user activities like request sms/call or verify tokens of the last 3 months.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

GET /dashboard/:format/application/users/activities

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.
q String Query to search logs by name, user email or user phone.
from Datetime Only activities from this date are returned. Any format is accepted, even "yesterday" or "2 weeks ago".
to Datetime Only activities until this date are returned. Any format is accepted, even "yesterday" or "2 weeks ago".
page Integer The page to display
per_page Integer The users to display per page (maximum 50)

Response

Name Type Description
activities Array List of Activity objects.

Example

Getting User activities.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/users/activities?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "activities": [
    {
      "created_at": "2014-08-18 21:44:21 UTC",
      "action_name": "verify_token",
      "user_email": "test@authy.com",
      "user_phone": "+1 650-324-3322"
    }
  ],
  "count": 1
}

Mark User for Health Check

Marks user for health check.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

POST /dashboard/:format/application/users/:id/health_check

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user Access Key.

Response

Name Type Description
success Boolean True when the user was marked for health check.

Example

Marking a user for health check.

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/users/23/health_check"

Sample response

{
  "success": true
}

Suspend User

Suspends a given User.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

POST /dashboard/:format/application/users/:id/suspend

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
success Boolean True when the user was suspended.

Example

Suspending a user

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/users/23/suspend"

Sample response

{
  "success": true
}

Unsuspend User

Unsuspends a given User.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

POST /dashboard/:format/application/users/:id/unsuspend

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
success Boolean True when the user was unsuspended.

Example

Unsuspending a user

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/users/23/unsuspend"

Sample response

{
  "success": true
}

Mark User For Deletion.

If you want to remove a User from your application you can use the move_to_trash API.
Note: Removing a user will immediately disable token verifications. Once a user has been removed, you can recover the user for up to 30 days. After 30 days, the user will be permanently deleted from your application.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

POST /dashboard/:format/application/users/:id/move_to_trash

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
success Boolean True when the user was marked for deletion.

Example

Marking a user for deletion

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/users/23/move_to_trash"

Sample response

{
  "success": true
}

Remove User From Trash

Removes User from trash. Meaning the user is restored.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: admins, collaborators and support agents

POST /dashboard/:format/application/users/:id/remove_from_trash

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
success Boolean True when the user was restored.

Example

Unsuspending a user

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/users/23/remove_from_trash"

Sample response

{
  "success": true
}

Rotate API keys

Regenerates an API key given its type.
Possible API key types are:

  • api_key
  • admin_api_key
  • app_api_key
  • support_api_key
  • api_signing_key

Accessible by: admins

You need to sign this request using the api_signing_key as described in the Signing Requests section.

POST /dashboard/:format/application/keys/:type/rotate

Parameters

Name Type Description
app_api_key String The API key of the application.
access_key String The user access key.
type String Either api_key, admin_api_key, app_api_key, support_api_key or api_signing_key.

Response

Name Type Description
success Boolean True when the API key was rotated.

Example

Rotating an API key of an Application

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/keys/api_key/rotate"

Sample response

{
  "success": true,
  "new_api_key": "B89uJGW2FG9YT00a0000000KC8nArNAN",
  "old_api_key": "NANrAn8CK0000000a00TY9GF2WGJu98B"
}

Revoke API keys

After rotating an API key it is automatically revoked after 24 hours. This end point allows you to rotate the API key before that period is over.
Possible API key types are:

  • api_key
  • admin_api_key
  • app_api_key
  • support_api_key
  • api_signing_key

Accessible by: admins

You need to sign this request using the api_signing_key as described in the Signing Requests section.

POST /dashboard/:format/application/keys/:type/revoke

Parameters

Name Type Description
app_api_key String The API key of the application.
access_key String The user access key.
type String Either api_key, admin_api_key, app_api_key, support_api_key or api_signing_key.

Response

Name Type Description
success Boolean True when the previous API key was revoked.

Example

Revokes the previous API key of an Application

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/keys/api_key/revoke"

Sample response

{
  "success": true
}

Generate By-Pass Code For User

Generates a secure code that can be used as authentication token.
By-Pass Codes are only valid for 15 minutes.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: support agents

GET /dashboard/:format/application/users/:id/generate_bypass_code

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
token String Code to bypass the 2-factor authentication.
valid_until Float Timestamp indicating the expiration date.
user_id Integer Id of the user that's going to use the code.

Example

Generating a By-Pass Code for a [user]

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/users/23/generate_bypass_code?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "token": "9084390277",
  "valid_until": 1429747564.5968451,
  "user_id": 23
}

Listing User Devices

Fetches the list of user's devices.
You need to sign this request using the api_signing_key as described in the Signing Requests section.

Accessible by: support agents

GET /dashboard/:format/application/users/:id/devices

Parameters

Name Type Description
app_api_key String The API key of the wanted application.
access_key String The user access key.

Response

Name Type Description
devices List List of Device objects.

Example

Getting the devices associated to the User

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     "https://api.authy.com/dashboard/json/application/users/23/devices?app_api_key=b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339&access_key=d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f"

Sample response

{
  "devices": [
      {
        "city": "Miami",
        "country": "United States",
        "device_type": "Android",
        "name": "Android",
        "needs_health_check": false,
        "region": null,
        "registered": true,
        "token": {
          "created_at": "2016-04-14T12:59:14Z",
          "locked": true,
          "id": "278809"
        },
        "device_id": 103
      }
  ],
  "success": true
}

Enable OneTouch

DEPRECATED. OneTouch is enabled by default for all applications and cannot be disabled.

Enable OneTouch in given application.

Accessible by: admins

You need to sign this request using the api_signing_key as described in the Signing Requests section.

PUT /dashboard/:format/application/onetouch/enable

Parameters

Name Type Description
app_api_key String The API key of the application.
access_key String The user access key.

Response

Name Type Description
success Boolean True when OneTouch has been enabled

Example

Enabling OneTouch in an Application

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -X PUT \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/onetouch/enable"

Sample response

{
 "message": "OneTouch was enabled."
  "success": true
}

Disable OneTouch

DEPRECATED. OneTouch is enabled by default for all applications and cannot be disabled.

Disable OneTouch in given application.

Accessible by: admins

You need to sign this request using the api_signing_key as described in the Signing Requests section.

PUT /dashboard/:format/application/onetouch/disable

Parameters

Name Type Description
app_api_key String The API key of the application.
access_key String The user access key.

Response

Name Type Description
success Boolean True when OneTouch has been enabled

Example

Disabling OneTouch in an Application

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -X PUT \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     "https://api.authy.com/dashboard/json/application/onetouch/disable"

Sample response

{
  "message": "OneTouch was disabled."
  "success": true
}

OneTouch callback url

Set OneTouch callback url in a given application.

Accessible by: admins

You need to sign this request using the api_signing_key as described in the Signing Requests section.

PUT /dashboard/:format/application/onetouch/callback

Parameters

Name Type Description
app_api_key String The API key of the application.
access_key String The user access key.
callback_method String the http method used by the call back (post | get).
callback_url String the url for the callback.

Response

Name Type Description
success Boolean True when callback has been set

Example

Setting OneTouch callback in an Application

curl -H "X-Authy-Signature: <signature>" -H "X-Authy-Signature-Nonce: <nonce>" \
     -X PUT \
     -d app_api_key="b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339" \
     -d access_key="d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f" \
     -d callback_method="post" \
     -d callback_url="https://example.com/receive_callback" \
     "https://api.authy.com/dashboard/json/application/onetouch/callback"

Sample response

{
  "message": "Callback information saved."
  "success": true
}
Rate this page:

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 by visiting our Twilio Community forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more