Auth0 logs API

openapi: 3.2.0
info:
  title: Auth0 Management Logs API
  description: Auth0 Management API v2.
  termsOfService: https://auth0.com/web-terms/
  contact:
    name: Auth0 Support
    url: https://support.auth0.com
  version: '2.0'
servers:
- url: https://{tenantDomain}/api/v2
  variables:
    tenantDomain:
      default: '{TENANT}.auth0.com'
      description: Auth0 Tenant Domain
security:
- bearerAuth: []
tags:
- name: logs
paths:
  /logs:
    get:
      summary: Search Log Events
      description: "Retrieve log entries that match the specified search criteria (or all log entries if no criteria specified).\n\nSet custom search criteria using the <code>q</code> parameter, or search from a specific log ID (<i>\"search from checkpoint\"</i>).\n\nFor more information on all possible event types, their respective acronyms, and descriptions, see <a href=\"https://auth0.com/docs/logs/log-event-type-codes\">Log Event Type Codes</a>.\n\n<h5>To set custom search criteria, use the following parameters:</h5>\n\n<ul>\n    <li><b>q:</b> Search Criteria using <a href=\"https://auth0.com/docs/logs/log-search-query-syntax\">Query String Syntax</a></li>\n    <li><b>page:</b> Page index of the results to return. First page is 0.</li>\n    <li><b>per_page:</b> Number of results per page.</li>\n    <li><b>sort:</b> Field to use for sorting appended with `:1` for ascending and `:-1` for descending. e.g. `date:-1`</li>\n    <li><b>fields:</b> Comma-separated list of fields to include or exclude (depending on include_fields) from the result, empty to retrieve all fields.</li>\n    <li><b>include_fields:</b> Whether specified fields are to be included (true) or excluded (false).</li>\n    <li><b>include_totals:</b> Return results inside an object that contains the total result count (true) or as a direct array of results (false, default). <b>Deprecated:</b> this field is deprecated and should be removed from use. See <a href=\"https://auth0.com/docs/product-lifecycle/deprecations-and-migrations/migrate-to-tenant-log-search-v3#pagination\">Search Engine V3 Breaking Changes</a></li>\n</ul>\n\nFor more information on the list of fields that can be used in <code>fields</code> and <code>sort</code>, see <a href=\"https://auth0.com/docs/logs/log-search-query-syntax#searchable-fields\">Searchable Fields</a>.\n\nAuth0 <a href=\"https://auth0.com/docs/logs/retrieve-log-events-using-mgmt-api#limitations\">limits the number of logs</a> you can return by search criteria to 100 logs per request. Furthermore, you may paginate only through 1,000 search results. If you exceed this threshold, please redefine your search or use the <a href=\"https://auth0.com/docs/logs/retrieve-log-events-using-mgmt-api#retrieve-logs-by-checkpoint\">get logs by checkpoint method</a>.\n\n<h5>To search from a checkpoint log ID, use the following parameters:</h5>\n<ul>\n    <li><b>from:</b> Log Event ID from which to start retrieving logs. You can limit the number of logs returned using the <code>take</code> parameter. If you use <code>from</code> at the same time as <code>q</code>, <code>from</code> takes precedence and <code>q</code> is ignored.</li>\n    <li><b>take:</b> Number of entries to retrieve when using the <code>from</code> parameter.</li>\n</ul>\n\n<strong>Important:</strong> When fetching logs from a checkpoint log ID, any parameter other than <code>from</code> and <code>take</code> will be ignored, and date ordering is not guaranteed.\n"
      tags:
      - logs
      parameters:
      - name: page
        in: query
        description: Page index of the results to return. First page is 0.
        schema:
          type: integer
          minimum: 0
      - name: per_page
        in: query
        description: ' Number of results per page. Paging is disabled if parameter not sent. Default: <code>50</code>. Max value: <code>100</code>'
        schema:
          type: integer
          minimum: 0
          maximum: 100
      - name: sort
        in: query
        description: Field to use for sorting appended with <code>:1</code>  for ascending and <code>:-1</code> for descending. e.g. <code>date:-1</code>
        schema:
          type: string
          pattern: ^((date)|(connection)|(client_id)|(client_name)|(ip)|(user_id)|(user_name)|(description)|(user_agent)|(type)|(details)|(strategy)|(strategy_type))\:(1|-1)$
      - name: fields
        in: query
        description: Comma-separated list of fields to include or exclude (based on value provided for <code>include_fields</code>) in the result. Leave empty to retrieve all fields.
        schema:
          type: string
          pattern: ^((date)|(connection)|(client_id)|(client_name)|(ip)|(user_id)|(user_name)|(description)|(user_agent)|(type)|(details)|(strategy)|(strategy_type))(,((date)|(connection)|(client_id)|(client_name)|(ip)|(user_id)|(user_name)|(description)|(user_agent)|(type)|(details)|(strategy)|(strategy_type)))*$
      - name: include_fields
        in: query
        description: Whether specified fields are to be included (<code>true</code>) or excluded (<code>false</code>)
        schema:
          type: boolean
      - name: include_totals
        in: query
        description: Return results as an array when false (default). Return results inside an object that also contains a total result count when true.
        schema:
          type: boolean
      - name: from
        in: query
        description: Log Event Id from which to start selection from.
        schema:
          type: string
      - name: take
        in: query
        description: Number of entries to retrieve when using the <code>from</code> parameter. Default <code>50</code>, max <code>100</code>
        schema:
          type: integer
      - name: search
        in: query
        description: 'Retrieves logs that match the specified search criteria. This parameter can be combined with all the others in the /api/logs endpoint but is specified separately for clarity.

          If no fields are provided a case insensitive ''starts with'' search is performed on all of the following fields: client_name, connection, user_name. Otherwise, you can specify multiple fields and specify the search using the %field%:%search%, for example: application:node user:"John@contoso.com".

          Values specified without quotes are matched using a case insensitive ''starts with'' search. If quotes are used a case insensitve exact search is used. If multiple fields are used, the AND operator is used to join the clauses.'
        schema:
          type: string
      responses:
        '200':
          description: Logs successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLogResponseContent'
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: read:logs, read:logs_users.'
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_logs
      x-release-lifecycle: GA
      x-operation-name: list
      x-operation-request-parameters-name: ListLogsRequestParameters
      x-operation-group: logs
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:logs
        - read:logs_users
  /logs/{id}:
    get:
      summary: Get a Log Event by Id
      description: Retrieve an individual log event.
      tags:
      - logs
      parameters:
      - name: id
        in: path
        description: log_id of the log to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Log successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLogResponseContent'
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: read:logs, read:logs_users.'
        '404':
          description: Log not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_logs_by_id
      x-release-lifecycle: GA
      x-operation-name: get
      x-operation-group: logs
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:logs
        - read:logs_users
components:
  schemas:
    LogLocationInfo:
      type: object
      description: Information about the location that triggered this event based on the `ip`.
      additionalProperties: true
      properties:
        country_code:
          type: string
          description: Two-letter <a href="https://www.iso.org/iso-3166-country-codes.html">Alpha-2 ISO 3166-1</a> country code.
          minLength: 2
          maxLength: 2
        country_code3:
          type: string
          description: Three-letter <a href="https://www.iso.org/iso-3166-country-codes.html">Alpha-3 ISO 3166-1</a> country code.
          minLength: 3
          maxLength: 3
        country_name:
          type: string
          description: Full country name in English.
        city_name:
          type: string
          description: Full city name in English.
        latitude:
          type: number
          description: Global latitude (horizontal) position.
        longitude:
          type: number
          description: Global longitude (vertical) position.
        time_zone:
          type: string
          description: Time zone name as found in the <a href="https://www.iana.org/time-zones">tz database</a>.
        continent_code:
          type: string
          description: Continent the country is located within. Can be `AF` (Africa), `AN` (Antarctica), `AS` (Asia), `EU` (Europe), `NA` (North America), `OC` (Oceania) or `SA` (South America).
    LogDateObject:
      type: object
      description: Date when the event occurred in ISO 8601 format.
      additionalProperties: true
    Log:
      type: object
      additionalProperties: true
      properties:
        date:
          $ref: '#/components/schemas/LogDate'
        type:
          type: string
          description: Type of event.
          default: sapi
        description:
          type:
          - string
          - 'null'
          description: Description of this event.
        connection:
          type: string
          description: Name of the connection the event relates to.
        connection_id:
          type: string
          description: ID of the connection the event relates to.
        client_id:
          type: string
          description: ID of the client (application).
          default: AaiyAPdpYdesoKnqjj8HJqRn4T5titww
        client_name:
          type: string
          description: Name of the client (application).
          default: My application Name
        ip:
          type: string
          description: IP address of the log event source.
          default: 190.257.209.19
        hostname:
          type: string
          description: Hostname the event applies to.
          default: 190.257.209.19
        user_id:
          type: string
          description: ID of the user involved in the event.
          default: auth0|56c75c4e42b6359e98374bc2
        user_name:
          type: string
          description: Name of the user involved in the event.
        audience:
          type: string
          description: API audience the event applies to.
        scope:
          type: string
          description: Scope permissions applied to the event.
          default: ''
        strategy:
          type: string
          description: Name of the strategy involved in the event.
        strategy_type:
          type: string
          description: Type of strategy involved in the event.
        log_id:
          type: string
          description: Unique ID of the event.
        isMobile:
          type: boolean
          description: Whether the client was a mobile device (true) or desktop/laptop/server (false).
        details:
          $ref: '#/components/schemas/LogDetails'
        user_agent:
          type: string
          description: User agent string from the client device that caused the event.
        security_context:
          $ref: '#/components/schemas/LogSecurityContext'
        location_info:
          $ref: '#/components/schemas/LogLocationInfo'
    ListLogOffsetPaginatedResponseContent:
      type: object
      additionalProperties: false
      properties:
        start:
          type: number
        limit:
          type: number
        length:
          type: number
        total:
          type: number
        logs:
          type: array
          items:
            $ref: '#/components/schemas/Log'
    GetLogResponseContent:
      type: object
      additionalProperties: true
      properties:
        date:
          $ref: '#/components/schemas/LogDate'
        type:
          type: string
          description: Type of event.
          default: sapi
        description:
          type:
          - string
          - 'null'
          description: Description of this event.
        connection:
          type: string
          description: Name of the connection the event relates to.
        connection_id:
          type: string
          description: ID of the connection the event relates to.
        client_id:
          type: string
          description: ID of the client (application).
          default: AaiyAPdpYdesoKnqjj8HJqRn4T5titww
        client_name:
          type: string
          description: Name of the client (application).
          default: My application Name
        ip:
          type: string
          description: IP address of the log event source.
          default: 190.257.209.19
        hostname:
          type: string
          description: Hostname the event applies to.
          default: 190.257.209.19
        user_id:
          type: string
          description: ID of the user involved in the event.
          default: auth0|56c75c4e42b6359e98374bc2
        user_name:
          type: string
          description: Name of the user involved in the event.
        audience:
          type: string
          description: API audience the event applies to.
        scope:
          type: string
          description: Scope permissions applied to the event.
          default: ''
        strategy:
          type: string
          description: Name of the strategy involved in the event.
        strategy_type:
          type: string
          description: Type of strategy involved in the event.
        log_id:
          type: string
          description: Unique ID of the event.
        isMobile:
          type: boolean
          description: Whether the client was a mobile device (true) or desktop/laptop/server (false).
        details:
          $ref: '#/components/schemas/LogDetails'
        user_agent:
          type: string
          description: User agent string from the client device that caused the event.
        security_context:
          $ref: '#/components/schemas/LogSecurityContext'
        location_info:
          $ref: '#/components/schemas/LogLocationInfo'
    LogDate:
      oneOf:
      - type: string
        description: Date when the event occurred in ISO 8601 format.
        default: '2016-02-23T19:57:29.532Z'
      - $ref: '#/components/schemas/LogDateObject'
    LogSecurityContext:
      type: object
      description: Information about security-related signals.
      additionalProperties: true
      properties:
        ja3:
          type: string
          description: JA3 fingerprint value.
        ja4:
          type: string
          description: JA4 fingerprint value.
    LogDetails:
      type: object
      description: Additional useful details about this event (structure is dependent upon event type).
      additionalProperties: true
    ListLogResponseContent:
      oneOf:
      - type: array
        items:
          $ref: '#/components/schemas/Log'
      - $ref: '#/components/schemas/ListLogOffsetPaginatedResponseContent'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: jwt
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token/
          x-form-parameters:
            audience: /api/v2/
          scopes:
            create:actions: Create Actions
            read:actions: Read Actions
            update:actions: Update Actions
            delete:actions: Delete Actions
            read:anomaly_blocks: Read Anomaly Blocks
            delete:anomaly_blocks: Delete Anomaly Blocks
            read:attack_protection: Read Attack Protection
            update:attack_protection: Update Attack Protection
            create:authentication_methods: Create Authentication Methods
            read:authentication_methods: Read Authentication Methods
            update:authentication_methods: Update Authentication Methods
            delete:authentication_methods: Delete Authentication Methods
            read:branding: Read Branding
            update:branding: Update Branding
            delete:branding: Delete Branding
            create:client_credentials: Create Client Credentials
            read:client_credentials: Read Client Credentials
            update:client_credentials: Update Client Credentials
            delete:client_credentials: Delete Client Credentials
            create:client_grants: Create Client Grants
            read:client_grants: Read Client Grants
            update:client_grants: Update Client Grants
            delete:client_grants: Delete Client Grants
            read:client_keys: Read Client Keys
            update:client_keys: Update Client Keys
            read:client_summary: Read Client Summary
            update:client_token_vault_privileged_access: Update Client Token Vault Privileged Access
            create:clients: Create Clients
            read:clients: Read Clients
            update:clients: Update Clients
            delete:clients: Delete Clients
            create:connection_profiles: Create Connection Profiles
            read:connection_profiles: Read Connection Profiles
            update:connection_profiles: Update Connection Profiles
            delete:connection_profiles: Delete Connection Profiles
            create:connections: Create Connections
            read:connections: Read Connections
            update:connections: Update Connections
            delete:connections: Delete Connections
            create:connections_keys: Create Connections Keys
            read:connections_keys: Read Connections Keys
            update:connections_keys: Update Connections Keys
            read:current_user: Read Current User
            delete:current_user: Delete Current User
            create:current_user_device_credentials: Create Current User Device Credentials
            delete:current_user_device_credentials: Delete Current User Device Credentials
            update:current_user_identities: Update Current User Identities
            update:current_user_metadata: Update Current User Metadata
            create:custom_domains: Create Custom Domains
            read:custom_domains: Read Custom Domains
            update:custom_domains: Update Custom Domains
            delete:custom_domains: Delete Custom Domains
            create:custom_signing_keys: Create Custom Signing Keys
            read:custom_signing_keys: Read Custom Signing Keys
            update:custom_signing_keys: Update Custom Signing Keys
            delete:custom_signing_keys: Delete Custom Signing Keys
            read:device_credentials: Read Device Credentials
            delete:device_credentials: Delete Device Credentials
            create:directory_provisionings: Create Directory Provisionings
            read:directory_provisionings: Read Directory Provisionings
            update:directory_provisionings: Update Directory Provisionings
            delete:directory_provisionings: Delete Directory Provisionings
            create:email_provider: Create Email Provider
            read:email_provider: Read Email Provider
            update:email_provider: Update Email Provider
            delete:email_provider: Delete Email Provider
            create:email_templates: Create Email Templates
            read:email_templates: Read Email Templates
            update:email_templates: Update Email Templates
            create:encryption_keys: Create Encryption Keys
            read:encryption_keys: Read Encryption Keys
            update:encryption_keys: Update Encryption Keys
            delete:encryption_keys: Delete Encryption Keys
            read:event_deliveries: Read Event Deliveries
            update:event_deliveries: Update Event Deliveries
            create:event_streams: Create Event Streams
            read:event_streams: Read Event Streams
            update:event_streams: Update Event Streams
            delete:event_streams: Delete Event Streams
            read:events: Read Events
            read:federated_connections_tokens: Read Federated Connections Tokens
            delete:federated_connections_tokens: Delete Federated Connections Tokens
            create:flows: Create Flows
            read:flows: Read Flows
            update:flows: Update Flows
            delete:flows: Delete Flows
            read:flows_executions: Read Flows Executions
            delete:flows_executions: Delete Flows Executions
            create:flows_vault_connections: Create Flows Vault Connections
            read:flows_vault_connections: Read Flows Vault Connections
            update:flows_vault_connections: Update Flows Vault Connections
            delete:flows_vault_connections: Delete Flows Vault Connections
            create:forms: Create Forms
            read:forms: Read Forms
            update:forms: Update Forms
            delete:forms: Delete Forms
            read:grants: Read Grants
            delete:grants: Delete Grants
            read:group_members: Read Group Members
            read:groups: Read Groups
            delete:groups: Delete Groups
            create:guardian_enrollment_tickets: Create Guardian Enrollment Tickets
            read:guardian_enrollments: Read Guardian Enrollments
            delete:guardian_enrollments: Delete Guardian Enrollments
            read:guardian_factors: Read Guardian Factors
            update:guardian_factors: Update Guardian Factors
            create:hooks: Create Hooks
            read:hooks: Read Hooks
            update:hooks: Update Hooks
            delete:hooks: Delete Hooks
            create:log_streams: Create Log Streams
            read:log_streams: Read Log Streams
            update:log_streams: Update Log Streams
            delete:log_streams: Delete Log Streams
            read:logs: Read Logs
            read:logs_users: Read Logs Users
            read:mfa_policies: Read Mfa Policies
            update:mfa_policies: Update Mfa Policies
            create:network_acls: Create Network Acls
            read:network_acls: Read Network Acls
            update:network_acls: Update Network Acls
            delete:network_acls: Delete Network Acls
            create:organization_client_grants: Create Organization Client Grants
            read:organization_client_grants: Read Organization Client Grants
            delete:organization_client_grants: Delete Organization Client Grants
            create:organization_connections: Create Organization Connections
            read:organization_connections: Read Organization Connections
            update:organization_connections: Update Organization Connections
            delete:organization_connections: Delete Organization Connections
            create:organization_discovery_domains: Create Organization Discovery Domains
            read:organization_discovery_domains: Read Organization Discovery Domains
            update:organization_discovery_domains: Update Organization Discovery Domains
            delete:organization_discovery_domains: Delete Organization Discovery Domains
            create:organization_invitations: Create Organization Invitations
            read:organization_invitations: Read Organization Invitations
            delete:organization_invitations: Delete Organization Invitations
            create:organization_member_roles: Create Organization Member Roles
            read:organization_member_roles: Read Organization Member Roles
            delete:organization_member_roles: Delete Organization Member Roles
            create:organization_members: Create Organization Members
            read:organization_members: Read Organization Members
            delete:organization_members: Delete Organization Members
            create:organizations: Create Organizations
            read:organizations: Read Organizations
            update:organizations: Update Organizations
            delete:organizations: Delete Organizations
            read:organizations_summary: Read Organizations Summary
            create:phone_providers: Create Phone Providers
            read:phone_providers: Read Phone Providers
            update:phone_providers: Update Phone Providers
            delete:phone_providers: Delete Phone Providers
            create:phone_templates: Create Phone Templates
            read:phone_templates: Read Phone Templates
            update:phone_templates: Update Phone Templates
            delete:phone_templates: Delete Phone Templates
            read:prompts: Read Prompts
            update:prompts: Update Prompts
            read:refresh_tokens: Read Refresh Tokens
            update:refresh_tokens: Update Refresh Tokens
            delete:refresh_tokens: Delete Refresh Tokens
            create:resource_servers: Create Resource Servers
            read:resource_servers: Read Resource Servers
            update:resource_servers: Update Resource Servers
            delete:resource_servers: Delete Resource Servers
            create:role_members: Create Role Members
            read:role_members: Read Role Members
            delete:role_members: Delete Role Members
            create:roles: Create Roles
            read:roles: Read Roles
            update:roles: Update Roles
            delete:roles: Delete Roles
            create:rules: Create Rules
            read:rules: Read Rules
            update:rules: Update Rules
            delete:rules: Delete Rules
            read:rules_configs: Read Rules Configs
            update:rules_configs: Update Rules Configs
            delete:rules_configs: Delete Rules Configs
            create:scim_config: Create Scim Config
            read:scim_config: Read Scim Config
            update:scim_config: Update Scim Config
            delete:scim_config: Delete Scim Config
            create:scim_token: Create Scim Token
            read:scim_token: Read Scim Token
            delete:scim_token: Delete Scim Token
            read:self_service_profile_custom_texts: Read Self Service Profile Custom Texts
            update:self_service_profile_custom_texts: Update Self Service Profile Custom Texts
            create:self_service_profiles: Create Self Service Profiles
            read:self_service_profiles: Read Self Service Profiles
            update:self_service_profiles: Update Self Service Profiles
            delete:self_service_profiles: Delete Self Service Profiles
            read:sessions: Read Sessions
            update:sessions: Update Sessions
            delete:sessions: Delete Sessions
            create:signing_keys: Create Signing Keys
            read:signing_keys: Read Signing Keys
            update:signing_keys: Update Signing Keys
            create:sso_access_tickets: Create Sso Access Tickets
            delete:sso_access_tickets: Delete Sso Access Tickets
            read:stats: Read Stats
            read:tenant_settings: Read Tenant Settings
            update:tenant_settings: Update Tenant Settings
            create:token_exchange_profiles: Create Token Exchange Profiles
            read:token_exchange_profiles: Read Token Exchange Profiles
            update:token_exchange_profiles: Update Token Exchange Profiles
            delete:token_exchange_profiles: Delete Token Exchange Profiles
            create:user_attribute_profiles: Create User Attribute Profiles
            read:user_attribute_profiles: Read User Attribute Profiles
            update:user_attribute_profiles: Update User Attribute Profiles
            delete:user_attribute_profiles: Delete User Attribute Profiles
            read:user_idp_tokens: Read User Idp Tokens
            create:user_tickets: Create User Tickets
            create:users: Create Users
            read:users: Read Users
            update:users: Update Users
            delete:users: Delete Users
            update:users_app_metadata: Update Users App Metadata
            create:vdcs_templates: Create Vdcs Templates
            read:vdcs_templates: Read Vdcs Templates
            update:vdcs_templates: Update Vdcs Templates
            delete:vdcs_templates: Delete Vdcs Templates
externalDocs:
  description: Auth0 Management API Documentation
  url: https://auth0.com/docs/api/management/v2/