On this page

Authy Dashboard API

(warning)

Warning

As of November 2022, Twilio no longer provides support for Authy SMS/Voice-only customers. Customers who were also using Authy TOTP or Push prior to March 1, 2023 are still supported. The Authy API is now closed to new customers and will be fully deprecated in the future.

For new development, we encourage you to use the Verify v2 API.

Existing customers will not be impacted at this time until Authy API has reached End of Life. For more information about migration, see Migrating from Authy to Verify for SMS.

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 parameters:

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.

1params = {b: "val|ue&2", a: "value1"}
2sorted_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.

1data = nonce + "|" + http_method + "|" + url + "|" + params_in_url_format
2"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.

1request.headers["X-Authy-Signature"] = digest_in_base64
2request.headers["X-Authy-Signature-Nonce"] = nonce
3make_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 they are 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 they haven't confirmed their 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"

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

Sample response

1{
2  "app_api_key": "b58778e69678da357d25c87cf02fc5e4ae1aef837da0d9bd4dada37e0375c339",
3  "api_signing_key": "3xhQiaC87dlUdOGbCmCeMYSBhtUt4vtc2DaCqI1WGBvhJo",
4  "access_key": "d2fa7a7177a537ae8503eb5ed90c8fd98c68c5395fbf6b6748202abd71c19a9f",
5  "api_key": "16e8a9f4ccc6982ab2b79f5d470f384a",
6  "app_id": 13234,
7  "name": "My New App",
8}

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.

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

Sample response

1{
2  "applications": [
3    {
4      "app_id": 13234,
5      "api_key": "public_api_key",
6      "app_api_key": "application_admin_api_key",
7      "name": "Dashboard Test",
8      "version": 8,
9      "users_count": 1324,
10      "hard_tokens_enabled": false,
11      "suspended": false,
12      "uses_voice_recording": false,
13      "twilio_account_sid": "twilio_account_id"
14    }
15  ],
16  "count": 1
17}
18

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.

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

Sample response

1{
2  "_id": "5081e6facaa71df429000002",
3  "value": "02dc1efe84b1409382fd901f8b6dfd430cc9369d7e8fb0994b42aee2db2c388d",
4  "user_id": 20,
5  "status": "active"
6}

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.

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

Sample response

1{
2  "access_keys": [
3    {
4      "_id": "5081e6facaa71df429000002",
5      "user_id": 20,
6      "status": "active"
7    }
8  ],
9  "count": 1
10}

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.

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

Sample response

1{
2  "_id": "5081e6facaa71df429000002",
3  "user_id": 20,
4  "status": "active"
5}

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

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

Sample response

1{
2  "_id": "5081e6facaa71df429000002",
3  "user_id": 20,
4  "status": "suspended"
5}

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

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

Sample response

1{
2  "_id": "5081e6facaa71df429000002",
3  "user_id": 20,
4  "status": "active"
5}

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

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

Sample response

1{
2  "deleted": true
3}

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

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

Sample response

1{
2  "app_id": 13234,
3  "api_key": "public_api_key",
4  "app_api_key": "application_admin_api_key",
5  "name": "New Dashboard Test",
6  "version": 8,
7  "users_count": 1324,
8  "hard_tokens_enabled": false,
9  "suspended": false,
10  "uses_voice_recording": false,
11  "twilio_account_sid": "twilio_account_id"
12}

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

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

Sample response

1{
2  "app_id": 13234,
3  "api_key": "public_api_key",
4  "app_api_key": "application_admin_api_key",
5  "name": "Dashboard Test",
6  "version": 8,
7  "users_count": 1324,
8  "hard_tokens_enabled": false,
9  "suspended": false,
10  "uses_voice_recording": false,
11  "twilio_account_sid": "twilio_account_id"
12}

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

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

Sample response

1{
2  "custom_assets": true,
3  "timer_color": "#000000",
4  "circle_color": "#000000",
5  "circle_background": "#000000",
6  "background_color": "#000000",
7  "labels_color": "#000000",
8  "labels_shadow_color": "#000000",
9  "token_color": "#000000"
10}

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

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

Sample response

1{
2  "custom_assets": true,
3  "timer_color": "#000000",
4  "circle_color": "#000000",
5  "circle_background": "#000000",
6  "background_color": "#ff0000",
7  "labels_color": "#000000",
8  "labels_shadow_color": "#000000",
9  "token_color": "#000000"
10}

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

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

Sample response

1{
2  "original_assets": {
3    "logo_url": "<url to the original logo>",
4    "sidebar_url": "<url to the original sidebar logo>"
5  },
6  "success": true
7}

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

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

Sample response

1{
2  "assets": {
3    "android": {
4      "med": {
5        "logo_url": "<logo url>",
6        "sidebar_url": "<logo url>"
7      },
8      "high": {
9        "logo_url": "<logo url>",
10        "sidebar_url": "<logo url>"
11      },
12      "extra_high": {
13        "logo_url": "<logo url>",
14        "sidebar_url": "<logo url>"
15      }
16    },
17    "ios": {
18      "med": {
19        "logo_url": "<logo url>",
20        "sidebar_url": "<logo url>"
21      },
22      "high": {
23        "logo_url": "<logo url>",
24        "sidebar_url": "<logo url>"
25      },
26      "extra_high": {
27        "logo_url": "<logo url>",
28        "sidebar_url": "<logo url>"
29      }
30    },
31    ...
32  },
33  "original_assets": {
34    "logo_url": "<url to the original logo>",
35    "sidebar_url": "<url to the original sidebar logo>"
36  },
37  "success": true
38}

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

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

Sample response

1{
2    "message": "Assets were processed",
3    "status": "finished",
4    "success": true
5}

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 they are 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 they haven't confirmed their 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

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

Sample response

1{
2  "welcome_message_enabled": true,
3  "force_sms": false,
4  "force_call": false,
5  "force_verification": true,
6  "sms_enabled": true,
7  "calls_enabled": true,
8  "call_requires_input": true
9}

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 they haven't confirmed their phone number. True by default.
`welcome_message_enabled`	Boolean	If true a welcome message will be sent to the user when they are 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 they are 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 they haven't confirmed their 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

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

Sample response

1{
2  "welcome_message_enabled": false,
3  "force_sms": false,
4  "force_call": false,
5  "force_verification": true,
6  "sms_enabled": true,
7  "calls_enabled": true,
8  "call_requires_input": true
9}

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

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

Sample response

1{
2  "deleted": true
3}

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.

Example

Suspending an application

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

Sample response

1{
2  "suspended": true
3}

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

Unsuspending an application

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

Sample response

1{
2  "suspended": false
3}

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.

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

Sample response

1{
2  "stats": [
3    {
4      "month": "082013",
5      "api_calls_count": 100,
6      "users_count": 40,
7      "auths_count": 1000,
8      "sms_count": 20,
9      "calls_count": 28,
10      "request_phone_info_count": 0,
11      "sms_verification_count": 0,
12      "call_verification_count": 0,
13      "check_verification_count": 0
14    }
15  ],
16  "count": 1
17}

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' phone number.

Response

Name	Type	Description
`users`	Array	List of User objects

Example

Getting Application users.

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

Sample response:

1{
2  "users": [
3    {
4      "authy_id": 23,
5      "used_at": "2013-08-18 21:10:43 UTC",
6      "confirmed": true,
7      "country_code": 1,
8      "cellphone": "650-XXX-9822",
9      "email": "sample@authy.com",
10      "last_sync_at": "2013-08-18 21:08:25 UTC",
11      "suspended": false,
12      "sms_enabled": true,
13      "status": "active",
14      "calls_enabled": true,
15      "removal_date": null
16    }
17  ],
18  "count": 1,
19  "total_count": 1
20}

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' 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.

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

Sample response

1{
2  "authy_id": 23,
3  "used_at": "2013-08-18 21:10:43 UTC",
4  "confirmed": true,
5  "country_code": 1,
6  "cellphone": "650-344-9822",
7  "email": "sample@authy.com",
8  "last_sync_at": "2013-08-18 21:08:25 UTC",
9  "suspended": false
10  "suspended": false,
11  "sms_enabled": true,
12  "status": "active",
13  "calls_enabled": true,
14  "removal_date": null
15}

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.

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

Sample response

1{
2  "activities": [
3    {
4      "created_at": "2014-08-18 21:44:21 UTC",
5      "action_name": "verify_token",
6      "user_email": "test@authy.com",
7      "user_phone": "+1 650-324-3322"
8    }
9  ],
10  "count": 1
11}

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.

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

Sample response

1{
2  "success": true
3}

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

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

Sample response

1{
2  "success": true
3}

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

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

Sample response

1{
2  "success": true
3}

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

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

Sample response

1{
2  "success": true
3}

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

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

Sample response

1{
2  "success": true
3}

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

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

Sample response

1{
2  "success": true,
3  "new_api_key": "B89uJGW2FG9YT00a0000000KC8nArNAN",
4  "old_api_key": "NANrAn8CK0000000a00TY9GF2WGJu98B"
5}

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

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

Sample response

1{
2  "success": true
3}

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]

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

Sample response

1{
2  "token": "9084390277",
3  "valid_until": 1429747564.5968451,
4  "user_id": 23
5}

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

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

Sample response

1{
2  "devices": [
3      {
4        "city": "Miami",
5        "country": "United States",
6        "device_type": "Android",
7        "name": "Android",
8        "needs_health_check": false,
9        "region": null,
10        "registered": true,
11        "token": {
12          "created_at": "2016-04-14T12:59:14Z",
13          "locked": true,
14          "id": "278809"
15        },
16        "device_id": 103
17      }
18  ],
19  "success": true
20}

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

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

Sample response

1{
2 "message": "OneTouch was enabled."
3  "success": true
4}

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

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

Sample response

1{
2  "message": "OneTouch was disabled."
3  "success": true
4}

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

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

Sample response

1{
2  "message": "Callback information saved."
3  "success": true
4}