audit.yml

openapi: "3.0.0"

info:
  version: 1.0.4
  title: Audit API
  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_
  x-label: Beta
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: "https://developer.nexmo.com/"
  termsOfService: "https://www.nexmo.com/terms-of-use"
  license:
    name: The MIT License (MIT)
    url: "https://opensource.org/licenses/MIT"

servers:
  - url: https://api.nexmo.com/beta/audit

paths:
  "/events":
    get:
      operationId: getEvents
      summary: Retrieve audit events
      description: >
        Get a series of audit events describing changes made to your
        Vonage API account over time.
      parameters:
        - name: event_type
          description: Filter results by this event type.
          in: query
          schema:
            $ref: "#/components/schemas/EventTypes"
        - name: date_from
          schema:
            type: string
          description: Start of time range for audit events. DateTime in ISO-8601 format.
          in: query
        - name: date_to
          schema:
            type: string
          description: End of time range for audit events. DateTime in ISO-8601 format.
          in: query
        - name: search_text
          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: page
          schema:
            type: string
          description: Page number starting with page 1.
          in: query
        - name: size
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
          description: Number of elements per page.
          in: query
      security:
        - basicAuth: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditResp"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorUnauthorized"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorForbidden"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorNotFound"

    options:
      operationId: getEventsOptions
      summary: Retrieve audit event types
      description: >
        Get audit event types.
      security:
        - basicAuth: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEventTypesResp"

        "204":
          description: No Content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NoContent"

        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorUnauthorized"

        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorForbidden"

  # GET event
  "/events/{id}":
    get:
      operationId: getEvent
      summary: Retrieve individual audit event
      description: >
        Get the specified audit event.
      parameters:
        - name: id
          schema:
            type: string
          description: The UUID of the audit event to retrieve
          in: path
          required: true
          example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      security:
        - basicAuth: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEvent"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorUnauthorized"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorNotFound"

components:
  schemas:
    EventTypes:
      type: string
      description: "The type of the audit event."
      example: "APP_CREATE"
      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

    AuditResp:
      type: object
      properties:
        _embedded:
          type: object
          description: Container containing the `events` array.
          properties:
            events:
              type: array
              items:
                $ref: "#/components/schemas/AuditEvent"
        _links:
          $ref: "#/components/schemas/PaginationLinks"
        page:
          $ref: "#/components/schemas/PaginationData"

    AuditEvent:
      type: object
      properties:
        id:
          type: string
          description: "UUID of the audit event"
          example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
        event_type:
          $ref: "#/components/schemas/EventTypes"
        event_type_description:
          type: string
          description: "A description of the event type"
          example: "Application created."
        created_at:
          type: string
          description: "When the audit event was created."
          example: "2018-07-04T11:41:32"
          format: date
        user_email:
          type: string
          description: "Email of the user whose account the audit event is associated with."
          format: email
          example: user@example.org
        user_id:
          type: integer
          description: "The ID of the user that the audit event is associated with."
          example: 1234567
        account_id:
          type: string
          description: "The NEXMO_API_KEY of the Vonage API account that the audit event is associated with."
          example: "abcd1234"
        source:
          type: string
          description: >
            The source of the event.

            CD: Customer Dashboard
            DEVAPI: via Developer API
          enum:
            - CD
            - DEVAPI
          example: CD
        source_ip:
          type: string
          format: ipv4
          description: The IP address used to make the account change.
          example: "192.0.2.0"
        source_description:
          type: string
          description: "Description of the audit event source."
          format: A human readable description of the `source`.
          enum:
            - Customer Dashboard
            - Developer API
          example: Customer Dashboard
        source_country:
          type: string
          description: ISO 3166-1 Alpha-2 country code recorded for the event.
          example: GB
        context:
          type: object
          description: A valid JSON object with information detailing the context of the audit event.
          oneOf:
            - $ref: "#/components/schemas/ContextAppCreate"
            - $ref: "#/components/schemas/ContextNumberLinking"
            - $ref: "#/components/schemas/ContextNumberUpdate"
            # TODO: there's a lot to add here!
          example:
            created:
              accountId: "abcdef01"
              appId: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
              name: My voice app
              answer_url:
                method: GET
                url: https://example.org/call
              type: voice
              event_url:
                method: POST
                url: https://example.org/event
        _links:
          $ref: "#/components/schemas/EventLink"

    AuditEventTypesResp:
      type: object
      properties:
        eventTypes:
          type: array
          description: An array of audit event types.
          items:
            $ref: "#/components/schemas/AuditEventType"

    AuditEventType:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/EventTypes"
        description:
          type: string
          example: "Application created."
          description: "A description of the event type"

    EventLink:
      type: object
      description: A link to this audit event object if you were to retrieve it individually.
      properties:
        self:
          properties:
            href:
              type: string
              format: uri
              description: URI of this document.
              example: "https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"

    PaginationLinks:
      type: object
      description: Container containing self, next and last page links.
      properties:
        self:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: URI of this document.
              example: "http://api.nexmo.com/beta/audit/events"
        next:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: URI of the next document.
              example: "http://api.nexmo.com/beta/audit/events?page=2&size=30"
        last:
          type: object
          properties:
            href:
              type: string
              format: uri
              description: URI of the last document in the sequence.
              example: "http://api.nexmo.com/beta/audit/events?page=2&size=30"

    PaginationData:
      type: object
      description: Page containing results.
      properties:
        size:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
          example: 100
          description: The total number of items in this response (page).
        totalElements:
          type: integer
          example: 120
          description: The total number of items across all pages.
        totalPages:
          type: integer
          example: 2
          description: The number of pages of data in the response.
        number:
          type: integer
          example: 1
          description: Which page of the pagination sequence you are looking at.

    CallbackUrl:
      type: object
      properties:
        method:
          type: string
          example: GET
          enum:
            - GET
            - POST
          description: "The HTTP method used to make a callback to your application"
        url:
          type: string
          example: "https://example.org/my-app-callback"
          format: url
          description: "The URL used for a callback to your application"

    ContextAppCreate:
      type: object
      properties:
        appId:
          type: string
          description: "UUID of the app that was created"
          example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
        created:
          type: object
          properties:
            accountId:
              type: string
              example: "abcdef01"
              description: "Which account the app is associated with"
            appId:
              type: string
              description: "UUID of the app that was created"
              example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
            name:
              type: string
              description: "The name of the application created"
              example: "My Voice App"
            answer_url:
              $ref: "#/components/schemas/CallbackUrl"
            event_url:
              $ref: "#/components/schemas/CallbackUrl"
            type:
              type: string
              example: "voice"
              description: "The type of application created"

    ContextNumberLinking:
      type: object
      properties:
        country:
          type: string
          description: "The country of the number"
          example: "GB"
        account:
          type: string
          description: "Which account the number is associated with"
          example: "abcdef01"
        msisdn:
          type: string
          description: "The phone number linked/unlinked to your application"
          example: "447000123456"
        applicationId:
          type: string
          description: "UUID of the app the number is being linked/unlinked to"
          example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"

    ContextNumberUpdate:
      type: object
      properties:
        country:
          type: string
          description: "The country of the number"
        msisdn:
          type: string
          description: "The phone number linked/unlinked to your application"
          example: "447000123456"
        voice-type:
          type: string
          enum:
            - tel
            - sip
            - vxml
            - app
          example: "app"
          description: "The type of endpoint the number has been forwarded to"
        voice-value:
          type: string
          description: "The value of the endpoint the number has been forwarded to"
          example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
        http:
          type: string
          format: url
          description: "The URL of the endpoint the number has been forwarded to"
          example: "https://example.org/my-app-callback"

    ErrorBadRequest:
      type: object
      properties:
        status:
          type: integer
          example: 400
          description: The HTTP Status code of the error
        error:
          type: string
          example: BadRequest
          description: A human readable description of the error
        message:
          type: string
          example: "This was a bad request."
          description: A longer description of the error

    ErrorUnauthorized:
      type: object
      properties:
        status:
          type: integer
          example: 401
          description: The HTTP Status code of the error
        error:
          type: string
          example: Unauthorized
          description: A human readable description of the error
        message:
          type: string
          example: 'Full authentication is required. JWT was not found in "Authorization" HTTP header.'
          description: A longer description of the error

    ErrorForbidden:
      type: object
      properties:
        status:
          type: integer
          example: 403
          description: The HTTP Status code of the error
        error:
          type: string
          example: Forbidden
          description: A human readable description of the error
        message:
          type: string
          example: "An example goes here"
          description: A longer description of the error

    ErrorNotFound:
      type: object
      properties:
        status:
          type: integer
          example: 404
          description: The HTTP Status code of the error
        error:
          type: string
          example: "Not Found"
          description: A human readable description of the error XXX
        message:
          type: string
          example: "Event with provided id: aaaaaaaa-bbbb-cccc-dddd-0123456789ab was not found"
          description: A longer description of the error YYY

    NoContent:
      type: object
      properties:
        status:
          type: integer
          example: 204
          description: The HTTP Status code of the error
        error:
          type: string
          example: "No Content"
          description: A human readable description of the error AAA
        message:
          type: string
          example: "No content"
          description: A longer description of the error BBB

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic