メニュー

Expand
Rate this page:

Thanks for rating this page!

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

Authy Reporting API

The Authy Reporting API offers powerful query capability to get detailed information about your application usage. The API has three report type endpoints:

  1. Events
  2. 日付ヒストグラム
  3. Terms

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

名前 概要
success
boolean
Returns true if the request was successful. (🏢 not PII )
events
配列
List of event objects. Each event contains the following fields:
  • event: name of the event.
  • time: time of the event in ISO8601 format.
  • request_id: UUID of the request.
  • objects: additional information about the event.
See examples for more details. (📇 PII)

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.

        
        
        
        
        Example shows Push Authentication responses from iPhones

        Events Reporting API Example

        Example shows Push Authentication responses from iPhones

        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:

        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
              
              
              
              
              Example shows user_added events over time

              Date Histogram Reporting API Example

              Example shows user_added events over time

              日付ヒストグラム

              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. (📇 PII)
              interval
              文字列(オプション)
              Default is "month". Allowed values are:
              • quarter
              • week
              • hour
              • minute
              Interval also supports time settings like "1.5h" (up to "w" for weeks).
              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

              名前 概要
              success
              boolean
              Returns true if the request was successful. (🏢 not PII )
              reports
              配列
              List of report objects. Each report contains the following fields
              • timestamp: interval timestamp in Epoch format.
              • time: interval time in ISO8601 format.
              • count: number of times the event occurred in the interval.
              (🏢 not PII )
                    
                    
                    
                    
                    Example shows aggregated summary of events by name for 2019

                    Terms Reporting API Example

                    Example shows aggregated summary of events by name for 2019

                    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

                    名前 概要
                    success
                    boolean
                    Returns true if the request was successful. (🏢 not PII )
                    terms
                    配列
                    List of term objects. Each term contains the following fields
                    • key: field grouping (String)
                    • count: number of occurrences within the scope (Integer)
                    (🏢 not PII )

                    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.

                          
                          
                          
                          
                          Use gte and lte operators to filter date ranges

                          Events: Get logs from December 17, 2019

                          Use gte and lte operators to filter date ranges
                                
                                
                                
                                
                                Returns all token events for March, April, and May. Page 2 with 5 results per page.

                                Events: Authentication Details Q2 2019

                                Returns all token events for March, April, and May. Page 2 with 5 results per page.
                                      
                                      
                                      
                                      
                                      Multiple reports in one request are supported

                                      Date Histogram: Get Invalid Tokens and Valid Tokens over time

                                      Multiple reports in one request are supported
                                            
                                            
                                            
                                            
                                            Summary of verified tokens for a specific 3 month range

                                            Date Histogram: Verified Tokens with Scope

                                            Summary of verified tokens for a specific 3 month range
                                                  
                                                  
                                                  
                                                  
                                                  Summary of authentications by Authy ID for November 2019. "key" is the Authy ID.

                                                  Terms: Monthly Active Users

                                                  Summary of authentications by Authy ID for November 2019. "key" is the Authy ID.
                                                        
                                                        
                                                        
                                                        
                                                        Summary of authentications by device type for all of 2019. "key" is the device type.

                                                        Terms: Authentications by Device Type

                                                        Summary of authentications by device type for all of 2019. "key" is the device type.

                                                        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

                                                        Rate this page:

                                                        ヘルプが必要ですか?

                                                        誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。