openapi: 3.0.0
servers:
  - url: https://api.nexmo.com/beta/audit
info:
  contact:
    email: devrel@vonage.com
    name: Vonage DevRel
    url: https://developer.nexmo.com/
  description: |
    The Vonage Audit API allows you to view details of changes to your account. More information is available at <https://developer.nexmo.com/audit/overview>.
    _Please note that the Audit API is currently in Beta_
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  title: Audit API
  version: 1.0.4
  x-label: Beta
  x-logo:
    url: https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/audit.yml
      version: "3.0"
  x-providerName: nexmo.com
  x-serviceName: audit
paths:
  /events:
    get:
      description: |
        Get a series of audit events describing changes made to your Vonage API account over time.
      operationId: getEvents
      parameters:
        - description: Filter results by this event type.
          in: query
          name: event_type
          schema:
            $ref: "#/components/schemas/EventTypes"
        - description: Start of time range for audit events. DateTime in ISO-8601 format.
          in: query
          name: date_from
          schema:
            type: string
        - description: End of time range for audit events. DateTime in ISO-8601 format.
          in: query
          name: date_to
          schema:
            type: string
        - description: Return only audit events where the JSON object contains this search text. Must be legal text for a JSON attribute value, that is quotes and braces must be escaped.
          in: query
          name: search_text
          schema:
            type: string
        - description: Page number starting with page 1.
          in: query
          name: page
          schema:
            type: string
        - description: Number of elements per page.
          in: query
          name: size
          schema:
            default: 30
            maximum: 100
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditResp"
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorUnauthorized"
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorForbidden"
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorNotFound"
          description: Not Found
      security:
        - basicAuth: []
      summary: Retrieve audit events
    options:
      description: |
        Get audit event types.
      operationId: getEventsOptions
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEventTypesResp"
          description: OK
        "204":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NoContent"
          description: No Content
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorUnauthorized"
          description: Unauthorized
        "403":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorForbidden"
          description: Forbidden
      security:
        - basicAuth: []
      summary: Retrieve audit event types
  /events/{id}:
    get:
      description: |
        Get the specified audit event.
      operationId: getEvent
      parameters:
        - description: The UUID of the audit event to retrieve
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEvent"
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorUnauthorized"
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorNotFound"
          description: Not Found
      security:
        - basicAuth: []
      summary: Retrieve individual audit event
components:
  schemas:
    AuditEvent:
      properties:
        _links:
          $ref: "#/components/schemas/EventLink"
        account_id:
          description: The NEXMO_API_KEY of the Vonage API account that the audit event is associated with.
          example: abcd1234
          type: string
        context:
          description: A valid JSON object with information detailing the context of the audit event.
          example:
            created:
              accountId: abcdef01
              answer_url:
                method: GET
                url: https://example.org/call
              appId: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
              event_url:
                method: POST
                url: https://example.org/event
              name: My voice app
              type: voice
          oneOf:
            - $ref: "#/components/schemas/ContextAppCreate"
            - $ref: "#/components/schemas/ContextNumberLinking"
            - $ref: "#/components/schemas/ContextNumberUpdate"
          type: object
        created_at:
          description: When the audit event was created.
          example: 2018-07-04T11:41:32
          format: date
          type: string
        event_type:
          $ref: "#/components/schemas/EventTypes"
        event_type_description:
          description: A description of the event type
          example: Application created.
          type: string
        id:
          description: UUID of the audit event
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
        source:
          description: |
            The source of the event.
            CD: Customer Dashboard DEVAPI: via Developer API
          enum:
            - CD
            - DEVAPI
          example: CD
          type: string
        source_country:
          description: ISO 3166-1 Alpha-2 country code recorded for the event.
          example: GB
          type: string
        source_description:
          description: Description of the audit event source.
          enum:
            - Customer Dashboard
            - Developer API
          example: Customer Dashboard
          format: A human readable description of the `source`.
          type: string
        source_ip:
          description: The IP address used to make the account change.
          example: 192.0.2.0
          format: ipv4
          type: string
        user_email:
          description: Email of the user whose account the audit event is associated with.
          example: user@example.org
          format: email
          type: string
        user_id:
          description: The ID of the user that the audit event is associated with.
          example: 1234567
          type: integer
      type: object
    AuditEventType:
      properties:
        description:
          description: A description of the event type
          example: Application created.
          type: string
        type:
          $ref: "#/components/schemas/EventTypes"
      type: object
    AuditEventTypesResp:
      properties:
        eventTypes:
          description: An array of audit event types.
          items:
            $ref: "#/components/schemas/AuditEventType"
          type: array
      type: object
    AuditResp:
      properties:
        _embedded:
          description: Container containing the `events` array.
          properties:
            events:
              items:
                $ref: "#/components/schemas/AuditEvent"
              type: array
          type: object
        _links:
          $ref: "#/components/schemas/PaginationLinks"
        page:
          $ref: "#/components/schemas/PaginationData"
      type: object
    CallbackUrl:
      properties:
        method:
          description: The HTTP method used to make a callback to your application
          enum:
            - GET
            - POST
          example: GET
          type: string
        url:
          description: The URL used for a callback to your application
          example: https://example.org/my-app-callback
          format: url
          type: string
      type: object
    ContextAppCreate:
      properties:
        appId:
          description: UUID of the app that was created
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
        created:
          properties:
            accountId:
              description: Which account the app is associated with
              example: abcdef01
              type: string
            answer_url:
              $ref: "#/components/schemas/CallbackUrl"
            appId:
              description: UUID of the app that was created
              example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
              type: string
            event_url:
              $ref: "#/components/schemas/CallbackUrl"
            name:
              description: The name of the application created
              example: My Voice App
              type: string
            type:
              description: The type of application created
              example: voice
              type: string
          type: object
      type: object
    ContextNumberLinking:
      properties:
        account:
          description: Which account the number is associated with
          example: abcdef01
          type: string
        applicationId:
          description: UUID of the app the number is being linked/unlinked to
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
        country:
          description: The country of the number
          example: GB
          type: string
        msisdn:
          description: The phone number linked/unlinked to your application
          example: "447000123456"
          type: string
      type: object
    ContextNumberUpdate:
      properties:
        country:
          description: The country of the number
          type: string
        http:
          description: The URL of the endpoint the number has been forwarded to
          example: https://example.org/my-app-callback
          format: url
          type: string
        msisdn:
          description: The phone number linked/unlinked to your application
          example: "447000123456"
          type: string
        voice-type:
          description: The type of endpoint the number has been forwarded to
          enum:
            - tel
            - sip
            - vxml
            - app
          example: app
          type: string
        voice-value:
          description: The value of the endpoint the number has been forwarded to
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
          type: string
      type: object
    ErrorBadRequest:
      properties:
        error:
          description: A human readable description of the error
          example: BadRequest
          type: string
        message:
          description: A longer description of the error
          example: This was a bad request.
          type: string
        status:
          description: The HTTP Status code of the error
          example: 400
          type: integer
      type: object
    ErrorForbidden:
      properties:
        error:
          description: A human readable description of the error
          example: Forbidden
          type: string
        message:
          description: A longer description of the error
          example: An example goes here
          type: string
        status:
          description: The HTTP Status code of the error
          example: 403
          type: integer
      type: object
    ErrorNotFound:
      properties:
        error:
          description: A human readable description of the error XXX
          example: Not Found
          type: string
        message:
          description: A longer description of the error YYY
          example: "Event with provided id: aaaaaaaa-bbbb-cccc-dddd-0123456789ab was not found"
          type: string
        status:
          description: The HTTP Status code of the error
          example: 404
          type: integer
      type: object
    ErrorUnauthorized:
      properties:
        error:
          description: A human readable description of the error
          example: Unauthorized
          type: string
        message:
          description: A longer description of the error
          example: Full authentication is required. JWT was not found in "Authorization" HTTP header.
          type: string
        status:
          description: The HTTP Status code of the error
          example: 401
          type: integer
      type: object
    EventLink:
      description: A link to this audit event object if you were to retrieve it individually.
      properties:
        self:
          properties:
            href:
              description: URI of this document.
              example: https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
              format: uri
              type: string
      type: object
    EventTypes:
      description: The type of the audit event.
      enum:
        - USER_STATUS
        - USER_UPDATE
        - USER_BILLING_UPDATE
        - USER_CREATE
        - USER_LOGIN
        - USER_LOGOUT
        - USER_PRODUCT_SEARCH
        - USER_API_KEYS_UPDATE
        - ACCOUNT_SECRET_DELETE
        - ACCOUNT_SECRET_CREATE
        - ACCOUNT_UPDATE_SPAMMER
        - ACCOUNT_UPDATE_SETTINGS_API
        - NUMBER_ASSIGN
        - NUMBER_UPDATED
        - NUMBER_RELEASE
        - NUMBER_LINKED
        - NUMBER_UNLINKED
        - APP_CREATE
        - APP_UPDATE
        - APP_DELETE
        - APP_DISABLE
        - APP_ENABLE
        - IP_WHITELIST_CREATE
        - IP_WHITELIST_DELETE
        - AUTORELOAD_ENABLE
        - AUTORELOAD_UPDATE
        - AUTORELOAD_DISABLE
      example: APP_CREATE
      type: string
    NoContent:
      properties:
        error:
          description: A human readable description of the error AAA
          example: No Content
          type: string
        message:
          description: A longer description of the error BBB
          example: No content
          type: string
        status:
          description: The HTTP Status code of the error
          example: 204
          type: integer
      type: object
    PaginationData:
      description: Page containing results.
      properties:
        number:
          description: Which page of the pagination sequence you are looking at.
          example: 1
          type: integer
        size:
          default: 30
          description: The total number of items in this response (page).
          example: 100
          maximum: 100
          minimum: 1
          type: integer
        totalElements:
          description: The total number of items across all pages.
          example: 120
          type: integer
        totalPages:
          description: The number of pages of data in the response.
          example: 2
          type: integer
      type: object
    PaginationLinks:
      description: Container containing self, next and last page links.
      properties:
        last:
          properties:
            href:
              description: URI of the last document in the sequence.
              example: http://api.nexmo.com/beta/audit/events?page=2&size=30
              format: uri
              type: string
          type: object
        next:
          properties:
            href:
              description: URI of the next document.
              example: http://api.nexmo.com/beta/audit/events?page=2&size=30
              format: uri
              type: string
          type: object
        self:
          properties:
            href:
              description: URI of this document.
              example: http://api.nexmo.com/beta/audit/events
              format: uri
              type: string
          type: object
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
