openapi: "3.0.0"

info:
  version: 1.0.2
  title: Nexmo Audit API
  description: >
    Nexmo's 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_
  contact:
    name: Nexmo DevRel
    email: devrel@nexmo.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
        Nexmo 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 Nexmo 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
