{ "openapi": "3.0.0", "info": { "version": "1.0.6", "title": "Audit API", "x-metaTitle": "Vonage Audit API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Audit API in this reference guide. Learn more in Vonage's API documentation.", "description": "The Vonage Audit API allows you to view details of changes to your account. More information is available at .\n_Please note that the Audit API is currently in Beta_\n", "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.\n", "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.\n", "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" } } } } } } }, "/events/{id}": { "get": { "operationId": "getEvent", "summary": "Retrieve individual audit event", "description": "Get the specified audit event.\n", "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-time" }, "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.\nCD: Customer Dashboard DEVAPI: via Developer API\n", "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" } ], "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", "description": "App Creation", "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", "description": "Number Linking", "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", "description": "Number Update", "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" } } } }