Skip to content
Permalink
main
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
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