Authy Reporting API
Authy offers reporting capabilities through a REST API. The API is designed to use HTTP response codes to indicate status. The body of the response will also include more information in JSON/XML. All of the events which are available to be queried using this API are visible in the sidebar under the "Queryable Events" heading.
The Authy Reporting API currently allows you to query data from the last 90 days from the current date.
API Endpoints
-
Currently the following endpoints exist: Events and Date Histogram.
-
These are /protected/ api calls requiring passage of an
X-Authy-API-Keyas a parameter
Query format
The query format follows the following pattern:
:param_name[:attribute][:operator]=:value
There are several params for each API endpoint. For example, for the List Events param name “query” you can specify attributes, operators and values like this:
query[objects.phone_verification.s_country_code][eq]=371
Supported operators
| Operator | Description |
|---|---|
| eq | Equal |
| lt | Less Than |
| lte | Less Than Equal |
| gt | Greater Than |
| gte | Greater Than Equal |
| lk | Like (similar to) |
Queryable Events
All of the events which are available to be queried using this API are visible in the sidebar under the "Queryable Events" heading.
Events
The following endpoint uses the querier service to list events.
GET /protected/:format/reporting/events
Parameters
| Name | Type | Description |
|---|---|---|
| query | String | Query to list the events. See query format (📇 PII ) |
| page | Integer | Pages to display (maximum is 100) (🏢 not PII ) |
| per_page | Integer | The events to display per request (maximum 100) (🏢 not PII ) |
Response
The response will be JSON or XML with the following structure:
events: list of events event: name of the event time: time of the event in iso8601 format request_id: The ID of the request objects: Objects involved in the event. This is specific by event type.
Rate limits
Rate limits are enforced by the Authy API to help ensure uptime. If your application hits the rate limit, an error will be returned and the app will be temporarily suspended. Time | Limit | Context :--- | :--- | :--- per minute | 30 | per app per hour | 300 | per app
Date Histogram
The following endpoint uses the querier service to return summaries of the queried events.
GET /protected/:format/reporting/date_histogram
Parameters
| Name | Type | Description |
|---|---|---|
| page | Integer | Page to display (maximum is 100) (🏢 not PII ) |
| per_page | Integer | The events to display per request (maximum 100). (🏢 not PII ) |
| interval | String | Allowed values are: "year", "quarter", "month", "week", "day", "hour", "minute". It also supports time settings like "1.5h" (up to "w" for weeks). (🏢 not PII ) |
| scope[ |
String | Defines a scope for the query, for example if you want to filter by user you can pass: scope[user.authy_id][eq]=20 and the result would only have data related to that user id. The operator can be: lt, lte, gt, gte, eq (See query format) (📇 PII ) |
| report[ |
String | Defines the queries and conditions to run, for example it can be: queries[sent]event[eq]=token_sent The operator can be: lt, lte, gt, gte, eq (See query format) (📇 PII ) |
Response
The response will be JSON or XML with the following structure:
interval: the given interval reports: For every <name of report> given: timestamp: timestamp for the point in time time: time in iso8601 format count: how many times was the event found in the given interval
Examples
Get phone verifications started using SMS
$ curl -H "X-Authy-API-Key: 2WaB..." 'https://api.authy.com/protected/json/reporting/events?query[objects.phone_verification.s_via][gt]=sms'
{ "events": [ { "event": "phone_verification_failed", "time": "2016-08-19T12:00:58.205Z", "request_id": "75315f1b90534980715a7eb7c1a701bc", "objects": { "app": { "account_sid": "ACfaf520dc5dd2b79e59685eb072b50730", "id": 322, "name": "8-digit", "type": "trial" }, "phone_verification": { "code_length": 4, "country_code": 1, "id": "6b98ecd0-4832-0134-6e68-0eb225da89af", "locale": "en", "phone_number": "a65739c2d6bc19dc98abded2d914d0fcb671a2001a3cce75d1bcc6dbba36927c", "seconds_to_expire": 559, "status": "pending", "via": "smsa" } } } ], "success": true }
Get logs from Oct 3, 2016
$ curl -H "X-Authy-API-Key: 2Wa..." 'http://api.authy.com/protected/json/reporting/events?query[time][gte]=2016-10-03T00:00:00.000Z&query[time][lte]=2016-10-03T23:59:59.999Z'
{ "events": [ { "event": "phone_verification_failed", "time": "2016-10-03T12:51:36.892Z", "request_id": "fe9dd05c4de093330e58e24e6d34dabe", "objects": { "app": { "account_sid": "ACfaf520dc5dd2b79e59685eb072b50730", "id": 322, "name": "8-digit", "type": "trial" }, "phone_verification": { "code_length": 4, "country_code": 371, "id": "0b5c34b0-6b96-0134-0f90-0617297a0a13", "locale": "en", "phone_number": "a9fe7da5dbec4797a264b894294a6ed202547adfd85732235108bc26fbd03e75", "seconds_to_expire": 599, "status": "pending", "via": "nana" } } }, { "event": "phone_verification_code_is_invalid", "time": "2016-10-03T13:01:35.295Z", "request_id": "a39253fabaad45979d7b034bf80ba119", "objects": { "app": { "account_sid": "ACfaf520dc5dd2b79e59685eb072b50730", "id": 322, "name": "8-digit", "type": "trial" }, "phone_verification": { "code_length": 4, "country_code": 371, "id": "0b5c34b0-6b96-0134-0f90-0617297a0a13", "locale": "en", "phone_number": "a9fe7da5dbec4797a264b894294a6ed202547adfd85732235108bc26fbd03e75", "seconds_to_expire": 1, "status": "pending", "via": "sms" } } } ], "success": true }
Get failed phone verifications
Passing the event phone_verification_failed will return the failed phone verifications.
Request: $ curl -H "X-Authy-API-Key: 2WaBmrIZYE8284ErM2RS5qRii4Ki3a7A" 'http://api.authy.com:4567/protected/json/reporting/events?query[event][eq]=phone_verification_failed'
Response: { "events": [ { "event": "phone_verification_failed", "time": "2016-10-03T12:51:36.892Z", "request_id": "fe9dd05c4de093330e58e24e6d34dabe", "objects": { "app": { "account_sid": "ACfaf520dc5dd2b79e59685eb072b50730", "id": 322, "name": "8-digit", "type": "trial" }, "phone_verification": { "code_length": 4, "country_code": 371, "id": "0b5c34b0-6b96-0134-0f90-0617297a0a13", "locale": "en", "phone_number": "a9fe7da5dbec4797a264b894294a6ed202547adfd85732235108bc26fbd03e75", "seconds_to_expire": 599, "status": "pending", "via": "nana" } } }, { "event": "phone_verification_failed", "time": "2016-08-19T02:07:20.939Z", "request_id": "75b2a30b30429383a8c6e5f27983ee7c", "objects": { "app": { "account_sid": "ACfaf520dc5dd2b79e59685eb072b50730", "id": 322, "name": "8-digit", "type": "trial" }, "phone_verification": { "code_length": 4, "country_code": 371, "id": "52d31870-47de-0134-6e67-0eb225da89af", "locale": "en", "phone_number": "a9fe7da5dbec4797a264b894294a6ed202547adfd85732235108bc26fbd03e75", "seconds_to_expire": 57, "status": "pending", "via": "nana" } } } ], "success": true }
Authentication Detail
Returns all token events (OneCode, TOTP) for March, April and May. Page 2, 10 results per page
Request:
curl -g "https://api.authy.com/protected/json/reporting/events?\ query[time][gte]=2017-03-01T00:00:00.000Z\ &query[time][lt]=2017-06-01T00:00:00.000Z\ &page=2\ &per_page=10\ &query[event][gte]=token_\ &query[event][lte]=totp_z" \ -H "X-Authy-API-Key: $AUTHY_API_KEY"
Response:
{ "events":[ { "event":"token_verified", "time":"2017-05-02T18:58:33.941Z", "request_id":"5c4163e4454f71cbe8a65e904634a1e3", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "token":{ "s_id":"40785821", "s_type":"SmsToken" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"totp_token_sent_via_call", "time":"2017-05-02T18:57:52.519Z", "request_id":"5408ccfe2545cb926cc5b69ec7ac8be5", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"token_verified", "time":"2017-05-02T18:56:04.981Z", "request_id":"9f4da95bccb1622d2e1c776caf46d30b", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "token":{ "s_id":"40785821", "s_type":"SmsToken" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"totp_token_sent", "time":"2017-05-02T18:55:52.127Z", "request_id":"b4e15f7670620ac6fbebff3d45740135", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"token_verified", "time":"2017-05-02T18:55:02.924Z", "request_id":"211230c4ba4a3694fbaa4502641cd3cc", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "device":{ "s_device_app":"authy", "s_device_type":"iphone", "s_errors":"", "s_id":"35890289", "s_ip":"70.214.84.244", "s_name":"iPhone", "s_user_agent":"Authy 20.2 rv:69 (iPhone; iPhone OS 9.3.3; en_US)", "s_version":"20.2", "t_creation_date":"2017-03-07T17:20:48.524Z", "t_last_used_date":"2017-05-02T18:55:02.898Z", "t_sync_date":"2017-05-02T18:54:38.845Z" }, "token":{ "b_locked":true, "s_id":"35890264" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"token_verified", "time":"2017-05-02T18:54:24.254Z", "request_id":"e071f3bf5341648386f57c1c3402f95f", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "device":{ "s_device_app":"authy", "s_device_type":"iphone", "s_errors":"", "s_id":"29269971", "s_ip":"216.177.99.226", "s_name":"iPhone 7 Personal", "s_user_agent":"Authy 20 rv:65 (iPhone; iPhone OS 10.0.1; en_US)", "s_version":"20.2", "t_creation_date":"2016-12-13T14:30:04.516Z", "t_last_used_date":"2017-05-02T18:54:24.232Z", "t_sync_date":"2017-05-02T18:53:42.529Z" }, "token":{ "b_locked":true, "s_id":"29269948" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"token_verified", "time":"2017-05-02T18:53:51.937Z", "request_id":"20be0245854b7b8b8d9a10f750673a11", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "device":{ "s_device_app":"authy", "s_device_type":"iphone", "s_errors":"", "s_id":"29269971", "s_ip":"216.177.99.226", "s_name":"iPhone 7 Personal", "s_user_agent":"Authy 20 rv:65 (iPhone; iPhone OS 10.0.1; en_US)", "s_version":"20.2", "t_creation_date":"2016-12-13T14:30:04.516Z", "t_last_used_date":"2017-05-02T18:53:51.911Z", "t_sync_date":"2017-05-02T18:53:42.529Z" }, "token":{ "b_locked":true, "s_id":"29269948" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"totp_token_sent", "time":"2017-05-02T13:05:44.978Z", "request_id":"287c77741986ded9a26e2c87de333b31", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "user":{ "as_authy_ids":[ "1357924" ], "b_banned":false, "s_authy_id":"1357924", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"token_verified", "time":"2017-05-02T13:04:23.478Z", "request_id":"18c4a23cd7c294233189598e0289dc75", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "device":{ "s_device_app":"authy", "s_device_type":"iphone", "s_errors":"", "s_id":"29269971", "s_ip":"66.65.101.299", "s_name":"iPhone 7 Personal", "s_user_agent":"Authy 20 rv:65 (iPhone; iPhone OS 10.0.1; en_US)", "s_version":"20.2", "t_creation_date":"2016-12-13T14:30:04.516Z", "t_last_used_date":"2017-05-02T13:04:23.454Z", "t_sync_date":"2017-05-02T13:03:52.567Z" }, "token":{ "b_locked":true, "s_id":"29269948" }, "user":{ "as_authy_ids":[ "23456789", "98765432" ], "b_banned":false, "s_authy_id":"23456789", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } }, { "event":"token_verified", "time":"2017-04-13T21:17:19.755Z", "request_id":"8dc6bf4096694a0c6eaf89dfa571089b", "objects":{ "app":{ "s_account_sid":"AC2bor01eeb93cf1fc6544c2346denotto", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "user":{ "as_authy_ids":[ "23456789", "98765432" ], "b_banned":false, "s_authy_id":"23456789", "s_country_code":"1", "s_errors":"", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da11111" } } } ], "success":true }
Authentication Summary
Returns a 3 data point summary, tokens sent (via sms/call/pushnotification), tokens successfully verifierd, tokens invalid, summarized by month, page 1, 50 results per page, March, April, May
Request:
curl -g "https://api.authy.com/protected/json/reporting/date_histogram?\ &report[totp_token_sent][event][eq]=totp_token_sent\ &report[token_verified][event][eq]=token_verified\ &report[token_invalid][event][eq]=token_invalid\ &scope[time][gte]=2017-03-01T00:00:00.000Z\ &scope[time][lt]=2017-06-01T00:00:00.000Z\ &interval=month\ &page=1\ &per_page=50" \ -H "X-Authy-API-Key: $AUTHY_API_KEY"
Response:
{ "interval":"month", "reports":{ "token_invalid":[ { "timestamp":1491004800000, "time":"2017-04-01T00:00:00.000Z", "count":3 }, { "timestamp":1493596800000, "time":"2017-05-01T00:00:00.000Z", "count":3 } ], "token_verified":[ { "timestamp":1491004800000, "time":"2017-04-01T00:00:00.000Z", "count":3 }, { "timestamp":1493596800000, "time":"2017-05-01T00:00:00.000Z", "count":7 } ], "totp_token_sent":[ { "timestamp":1491004800000, "time":"2017-04-01T00:00:00.000Z", "count":0 }, { "timestamp":1493596800000, "time":"2017-05-01T00:00:00.000Z", "count":4 } ] }, "success":true }
Phone Verification Detail
Returns all phone verification events for April
Request:
curl -g "https://api.authy.com/protected/json/reporting/events?\ query[time][gte]=2017-04-01T00:00:00.000Z\ &query[time][lt]=2017-05-01T00:00:00.000Z\ &query[event][gte]=phone_verification_\ &query[event][lt]=phone_verification_z" \ -H "X-Authy-API-Key: $AUTHY_API_KEY"
Response:
{ "events":[ { "event":"phone_verification_started", "time":"2017-04-21T18:38:32.635Z", "request_id":"dcdf34ef998c28786c368ff71493722d", "objects":{ "app":{ "s_account_sid":"AC2b8781eeb93cf1fc6544c2346de9e6a5", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "phone_verification":{ "i_seconds_to_expire":599, "line_type":"cellphone", "mccmnc":"310012", "s_code_length":"4", "s_country_code":"1", "s_errors":"", "s_id":"a515ba00-08ef-0135-b187-0a19a44cf006", "s_locale":"en", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da97602", "s_status":"pending", "s_via":"sms" } } }, { "event":"phone_verification_code_is_valid", "time":"2017-04-21T18:32:30.601Z", "request_id":"2b27640665a172513e2fa4a56f1d3d35", "objects":{ "app":{ "s_account_sid":"AC2b8781eeb93cf1fc6544c2346de9e6a5", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "phone_verification":{ "i_seconds_to_expire":398, "line_type":"cellphone", "mccmnc":"310012", "s_code_length":"4", "s_country_code":"1", "s_errors":"", "s_id":"55847910-08ee-0135-3004-0e5d6a065904", "s_locale":"es", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da97602", "s_status":"verified", "s_via":"call" } } }, { "event":"phone_verification_started", "time":"2017-04-21T18:31:16.832Z", "request_id":"91193999a075d3fb72b4dd1b5ad9d671", "objects":{ "app":{ "s_account_sid":"AC2b8781eeb93cf1fc6544c2346de9e6a5", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "phone_verification":{ "i_seconds_to_expire":472, "line_type":"cellphone", "mccmnc":"310012", "s_code_length":"4", "s_country_code":"1", "s_errors":"", "s_id":"55847910-08ee-0135-3004-0e5d6a065904", "s_locale":"es", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da97602", "s_status":"pending", "s_via":"call" } } }, { "event":"phone_verification_started", "time":"2017-04-21T18:30:57.99Z", "request_id":"232cf89bb8a6246ecfb9bba0464e2868", "objects":{ "app":{ "s_account_sid":"AC2b8781eeb93cf1fc6544c2346de9e6a5", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "phone_verification":{ "i_seconds_to_expire":491, "line_type":"cellphone", "mccmnc":"310012", "s_code_length":"4", "s_country_code":"1", "s_errors":"", "s_id":"55847910-08ee-0135-3004-0e5d6a065904", "s_locale":"es", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da97602", "s_status":"pending", "s_via":"call" } } }, { "event":"phone_verification_started", "time":"2017-04-21T18:29:09.631Z", "request_id":"4e019ca385f095cc8a19688b710a258f", "objects":{ "app":{ "s_account_sid":"AC2b8781eeb93cf1fc6544c2346de9e6a5", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "phone_verification":{ "i_seconds_to_expire":599, "line_type":"cellphone", "mccmnc":"310012", "s_code_length":"4", "s_country_code":"1", "s_errors":"", "s_id":"55847910-08ee-0135-3004-0e5d6a065904", "s_locale":"es", "s_phone_number":"f2527ef9a36461822fb9a793efbfcfbd9da97602", "s_status":"pending", "s_via":"call" } } }, { "event":"phone_verification_started", "time":"2017-04-19T16:35:52.083Z", "request_id":"ded6c2394bf9c95edb8fd513eb55b7ba", "objects":{ "app":{ "s_account_sid":"AC2b8781eeb93cf1fc6544c2346de9e6a5", "s_device_app":null, "s_errors":"", "s_id":"15861", "s_name":"OwlBank", "s_type":"full" }, "phone_verification":{ "i_seconds_to_expire":599, "line_type":"cellphone", "mccmnc":"310150", "s_code_length":"4", "s_country_code":"1", "s_errors":"", "s_id":"2d0863d0-074c-0135-b933-0a77bbe8093e", "s_locale":"en", "s_phone_number":"a5f02bcfd3d852190576f440c1d9cadf50153f4a", "s_status":"pending", "s_via":"sms" } } } ], "success":true }
Phone Verification Summary
Returns a 3 data point summary, phone verifications started, valid, invalid, for country code 1, March, April, May, by week, page 1, 50 results per page
Request:
curl -g "https://api.authy.com/protected/json/reporting/date_histogram?\ report[phone_verification_started][event][eq]=phone_verification_started\ &report[phone_verification_code_is_invalid][event][eq]=phone_verification_code_is_invalid\ &report[phone_verification_code_is_valid][event][eq]=phone_verification_code_is_valid\ &scope[objects.phone_verification.s_country_code][eq]=1\ &scope[time][gte]=2017-03-01T00:00:00.000Z\ &scope[time][lt]=2017-06-01T00:00:00.000Z\ &interval=week\ &page=1\ &per_page=50" \ -H "X-Authy-API-Key: $AUTHY_API_KEY"
Response:
{ "interval":"week", "reports":{ "phone_verification_code_is_invalid":[ { "timestamp":1492387200000, "time":"2017-04-17T00:00:00.000Z", "count":0 } ], "phone_verification_code_is_valid":[ { "timestamp":1492387200000, "time":"2017-04-17T00:00:00.000Z", "count":1 } ], "phone_verification_started":[ { "timestamp":1492387200000, "time":"2017-04-17T00:00:00.000Z", "count":5 } ] }, "success":true }
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.