Audit API

Beta

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

Download OAS 3 Definition

Improve this specification

Available Operations:

get Retrieve audit events
options Retrieve audit event types
get Retrieve individual audit event

Retrieve audit events

Get a series of audit events describing changes made to your Vonage API account over time.

GET


        https://api.nexmo.com/beta/audit/events

Host


        https://api.nexmo.com

GET


        /beta/audit/events

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Query Parameter

event_type

string

Filter results by this event type.

Must be one of: 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 or AUTORELOAD_DISABLE

date_from

string

Start of time range for audit events. DateTime in ISO-8601 format.

date_to

string

End of time range for audit events. DateTime in ISO-8601 format.

search_text

string

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.

page

string

Page number starting with page 1.

size

integer | Default: 30

Number of elements per page.

Responses

200 OK

_embedded

object

Container containing the events array.

array of objects

string

UUID of the audit event

string

The type of the audit event.

One of: 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 or AUTORELOAD_DISABLE

string

A description of the event type

string

When the audit event was created.

string

Email of the user whose account the audit event is associated with.

integer

The ID of the user that the audit event is associated with.

string

The NEXMO_API_KEY of the Vonage API account that the audit event is associated with.

string

The source of the event. CD: Customer Dashboard DEVAPI: via Developer API

One of: CD or DEVAPI

string

The IP address used to make the account change.

string

Description of the audit event source.

One of: Customer Dashboard or Developer API

string

ISO 3166-1 Alpha-2 country code recorded for the event.

object

A valid JSON object with information detailing the context of the audit event.

page

object

Page containing results.

integer

The total number of items in this response (page).

integer

The total number of items across all pages.

integer

The number of pages of data in the response.

integer

Which page of the pagination sequence you are looking at.

Example Responses

200 401 403 404

{
  "_embedded": {
    "events": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "event_type": "APP_CREATE",
        "event_type_description": "Application created.",
        "created_at": "2018-07-04T11:41:32",
        "user_email": "user@example.org",
        "user_id": 1234567,
        "account_id": "abcd1234",
        "source": "CD",
        "source_ip": "192.0.2.0",
        "source_description": "Customer Dashboard",
        "source_country": "GB",
        "context": {
          "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": {
          "self": {
            "href": "https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://api.nexmo.com/beta/audit/events"
    },
    "next": {
      "href": "http://api.nexmo.com/beta/audit/events?page=2&size=30"
    },
    "last": {
      "href": "http://api.nexmo.com/beta/audit/events?page=2&size=30"
    }
  },
  "page": {
    "size": 100,
    "totalElements": 120,
    "totalPages": 2,
    "number": 1
  }
}

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required. JWT was not found in \"Authorization\" HTTP header."
}

{
  "status": 403,
  "error": "Forbidden",
  "message": "An example goes here"
}

{
  "status": 404,
  "error": "Not Found",
  "message": "Event with provided id: aaaaaaaa-bbbb-cccc-dddd-0123456789ab was not found"
}

Retrieve audit event types

Get audit event types.

OPTIONS


        https://api.nexmo.com/beta/audit/events

Host


        https://api.nexmo.com

OPTIONS


        /beta/audit/events

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Responses

200 OK

eventTypes

array of objects

An array of audit event types.

string

The type of the audit event.

string

A description of the event type

204 No Content

status

integer

The HTTP Status code of the error

error

string

A human readable description of the error AAA

message

string

A longer description of the error BBB

Example Responses

200 204 401 403

{
  "eventTypes": [
    {
      "type": "APP_CREATE",
      "description": "Application created."
    }
  ]
}

{
  "status": 204,
  "error": "No Content",
  "message": "No content"
}

No Content

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required. JWT was not found in \"Authorization\" HTTP header."
}

{
  "status": 403,
  "error": "Forbidden",
  "message": "An example goes here"
}

Retrieve individual audit event

Get the specified audit event.

GET


        https://api.nexmo.com/beta/audit/events/:id

Host


        https://api.nexmo.com

GET


        /beta/audit/events/:id

Authentication

Key	Description	Example	Default
Authorization	Base64 encoded API key and secret joined by a colon. Read more	`Basic <base64>`	None

Path Parameters

string | Required

The UUID of the audit event to retrieve

Responses

200 OK

string

UUID of the audit event

event_type

string

The type of the audit event.

event_type_description

string

A description of the event type

created_at

string

When the audit event was created.

user_email

string

Email of the user whose account the audit event is associated with.

user_id

integer

The ID of the user that the audit event is associated with.

account_id

string

The NEXMO_API_KEY of the Vonage API account that the audit event is associated with.

source

string

The source of the event. CD: Customer Dashboard DEVAPI: via Developer API

One of: CD or DEVAPI

source_ip

string

The IP address used to make the account change.

source_description

string

Description of the audit event source.

One of: Customer Dashboard or Developer API

source_country

string

ISO 3166-1 Alpha-2 country code recorded for the event.

context

object

A valid JSON object with information detailing the context of the audit event.

Example Responses

200 401 404

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "event_type": "APP_CREATE",
  "event_type_description": "Application created.",
  "created_at": "2018-07-04T11:41:32",
  "user_email": "user@example.org",
  "user_id": 1234567,
  "account_id": "abcd1234",
  "source": "CD",
  "source_ip": "192.0.2.0",
  "source_description": "Customer Dashboard",
  "source_country": "GB",
  "context": {
    "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": {
    "self": {
      "href": "https://api.nexmo.com/beta/audit/events/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  }
}

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required. JWT was not found in \"Authorization\" HTTP header."
}

{
  "status": 404,
  "error": "Not Found",
  "message": "Event with provided id: aaaaaaaa-bbbb-cccc-dddd-0123456789ab was not found"
}