Authy Reporting 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 Reporting API offers powerful query capability to get detailed information about your application usage. The API has three report type endpoints:
Events
GET https://api.authy.com/protected/{FORMAT}/reporting/events
URL
| 名前 | 概要 |
|---|---|
FORMAT文字列 |
REST API呼び出しからの返却に想定されるフォーマットです。 json or xml. |
パラメーター
| 名前 | 概要 |
|---|---|
query文字列（オプション） |
Query to filter list of events in response. Default is everything. See query format (📇 PII) |
page 整数（オプション） |
Page within paginated results to display. Default is 1. (🏢 not PII ) |
per_page整数（オプション） |
Number of events to display per request. Default is 50. Maximum is 100. (🏢 not PII ) |
レスポンス
Response will either be in json or xml format depending on the format provided in the URL
| 名前 | 概要 |
|---|---|
successboolean |
Returns true if the request was successful. (🏢 not PII ) |
events配列 |
List of event objects. Each event contains the following fields:
|
Use the -g (same as --globoff) option to switch off the "URL globbing parser" and allow cURL to process the square brackets in the query parameters.
Query Format
Queries to the Events Reporting API follow the following pattern:
:query[:attribute][:operator]=:value
Supported Attributes and Available Events
Report queries can be filtered by the following events:
- account_recovery_approved
- account_recovery_canceled
- account_recovery_started
- custom_message_not_allowed
- device_registration_completed
- multidevice_setting_changed
- one_touch_request_responded (note: one_touch refers to the Authy Push Authentication API
- phone_change_canceled
- phone_change_pin_sent
- phone_change_requested
- suspended_account
- token_invalid
- token_verified
- too_many_code_verifications
- totp_token_sent_via_call
- totp_token_sent
- unlock_method_changed
- user_account_deleted
- user_added
- user_phone_changed
The following events are specific to our legacy phone verification API. Please consider upgrading to Verify V2:
Queries can filter based on top level event details like name:
query[event][eq]=one_touch_request_responded
Queries can also filter based on nested parameters like device type:
query[objects.device.s_device_type][eq]=iphone
Multiple queries in one request are supported:
query[event][eq]=totp_token_sent&query[objects.user.s_locale][eq]=en
Supported Operators
The following operators can be used to compare and filter event attributes.
| Operator | 概要 |
eq |
Equal to |
lt |
Less than |
lte |
Less than or Equal to |
gt |
Greater than |
gte |
Greater than or Equal to |
lk |
Like or similar to |
日付ヒストグラム
The following endpoint uses the querier service to return summaries over time of the queried events.
GET https://api.authy.com/protected/{FORMAT}/reporting/date_histogram
URL
| 名前 | 概要 |
|---|---|
FORMAT文字列 |
REST API呼び出しからの返却に想定されるフォーマットです。 json or xml. |
パラメーター
| 名前 | 概要 |
|---|---|
report[:report_name][:attribute][:operator]文字列（必須） |
Defines the queries to run, no reports returned if omitted.
|
interval文字列（オプション） |
Default is "month". Allowed values are:
|
scope[:attribute][:operator]文字列（オプション） |
Defines a filter for the query. Multiple scopes are supported. For example scope[user.authy_id][eq]=123 will only return results for that user. See query format and supported operators. (📇 PII) |
page 整数（オプション） |
Page within paginated results to display. Default is 1. (🏢 not PII ) |
per_page整数（オプション） |
Number of events to display per request. Default is 50. Maximum is 100. (🏢 not PII ) |
レスポンス
Response will either be in json or xml format depending on the format provided in the URL
| 名前 | 概要 |
|---|---|
successboolean |
Returns true if the request was successful. (🏢 not PII ) |
reports配列 |
List of report objects. Each report contains the following fields
|
Terms
The following endpoint groups by field to roll-up summaries of specific attributes.
GET https://api.authy.com/protected/{FORMAT}/reporting/terms
URL
| 名前 | 概要 |
|---|---|
FORMAT文字列 |
REST API呼び出しからの返却に想定されるフォーマットです。 json or xml. |
パラメーター
| 名前 | 概要 |
|---|---|
field文字列（必須） |
Defines the attribute to group by. Only one field is supported per query. Queries can group by top level event details like name (event) or nested parameters like device type (objects.device.s_device_type). For a list of supported events and their fields, see Supported Attributes. (📇 PII) |
size整数（オプション） |
Number of terms to return. Default is 10. Maximum is 100. (🏢 not PII ) |
scope[:attribute][:operator]文字列（オプション） |
Defines a filter for the query. Multiple scopes are supported. For example scope[user.authy_id][eq]=123 will only return results for that user. See query format and supported operators. (📇 PII ) |
レスポンス
Response will either be in json or xml format depending on the format provided in the URL
サンプル
Seeing this error?
[globbing] bad range in column
Make sure to use the -g (same as --globoff) option to switch off the "URL globbing parser" and allow cURL to process the square brackets in the query parameters.
Rate Limits
Rate limits are enforced by the Authy API. If your application hits the rate limit, an error will be returned and the app will be temporarily suspended.
| Limit | time | コンテキスト |
| 30 | / 分 | per application |
| 300 | per hour | per application |
ヘルプが必要ですか？
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.