Audit Logs REST API Reference


Use the Audit Logs REST API to get logs about the history of calls made to Skill Management APIs (SMAPI). The logs include information about each REST API operation, such as the operation name, timestamp, and source. The logs don't show any information about customer actions.

You can use the Audit Logs API in the following ways:

  • As an independent developer, use the API to get logs of all operations related to your Alexa skill.
  • As a tool-builder, give the developer user a way to view the logs of operations performed in tool that you build and distribute. The Audit Logs API limits the logs to the user-specific history of operations performed by the same developer tool.

Workflow for an independent developer

To get audit logs as an independent developer, you must have an Amazon developer account. You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.

If you plan to develop and configure Alexa skills by using the command line, download and install the Alexa Skills Kit Command Line Interface (ASK CLI). If you only get audit logs for skills that you or your organization create, you don't need the ASK CLI. However, you can use the ASK CLI to get an access token for the Audit Logs API.

To get the audit logs as an independent developer

  1. Create a Login with Amazon (LWA) security profile and get an access token. For details, see Get an Access Token for SMAPI.
  2. Use the access token to request audit logs with the Get audit logs operation. Specify the endpoint and filters for the operations that you want to show in the audit logs.
  3. The logs include the operations performed across all your tools.

Workflow for a tool-builder

If you're a tool-builder, take the following steps to provide the tool-specific audit logs to the user of your developer tool.

To build your tool to use the Audit Logs API

  1. In the tool, authenticate the user through the standard LWA authentication flow to get an access token for the user. For more details, see Get an Access Token for SMAPI.
  2. Use the access token to call the LWA API to Obtain Customer Profile Information. The LWA API returns the user identifier, name, and email address for the user.
  3. In the database that you maintain for the tool, save the user ID, name, and email address.
  4. Call the Get audit logs operation.
  5. In the data retrieved for the audit logs, for each requester.userId, get the name and email address from your database.
  6. When you display the audit logs in the tool, instead of showing the user ID, show the name and email address of the user.

API endpoint

The endpoint of the Audit Logs is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The Audit Logs API includes the following operations.

Operation HTTP method and URI

Get audit logs

POST /v1/developmentAuditLogs/query

Get audit logs

Get the audit log history of the SMAPI calls made by a developer or developers with permissions on the account.

Request

To get the audit log history, you make a POST request to the developmentAuditLogs resource.

Request path and header example

Copied to clipboard.

POST /v1/developmentAuditLogs/query
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "vendorId": "your.vendor.id.1",
    "requestFilters": {
        "resources": [{
            "id": "amzn1.ask.skill.1",
            "type": "Skill"
        }],
        "requesters": [{
            "userId": "amzn1.account.1"
        }],
        "httpResponseCodes": [
            "200",
            "202"
        ],
        "operations": [{
                "name": "getSkillManifest",
                "version": "v1"
            },
            {
                "name": "getUtteranceData",
                "version": "v1"
            }
        ],
        "startTime": "2019-06-01T22:58:24.0Z",
        "endTime": "2019-0-08T22:58:24.0Z"
    },
    "sortDirection": "DESC",
    "sortField": "timestamp",
    "paginationContext": {
        "nextToken": "someToken1",
        "maxResults": 2
    }
}

Request body properties

Property Description Type Required

vendorId

Identifies the vendor that requests the logs.
For details about how to get your vendor ID, see Locate your customer ID and vendor ID.

String

Yes

requestFilters

Return the audit logs based on the specified filter criteria.

Object

No

requestFilters.clients

List of client IDs.

Array of object

No

requestFilters.clients[].id

Identifier for your developer tool that the developer uses to manage their skills and skill-related resources. The id is the LWA client identifier associated with the LWA security profile. To view your client ID or create a new client ID, open the LWA console.
Format as a UUID. For actions performed on developer.amazon.com, set to Alexa Developer Console.
If you're a tool-builder, don't specify the client ID because the audit logs already filter to show only the operations performed by your client. As a tool-builder, specifying a different client ID causes an error.

String

Yes

requestFilters.operations

List of operation names and versions. For valid values, see Operation names and versions.

Array of objects

No

requestFilters.operations[].name

Name of the operation.

String

Yes

requestFilters.operations[].version

Version of the operation.

String

No

requestFilters.resources

List of resources or resource types.
You must provide at least the id or type.

Array of objects

No

requestFilters.resources[].id

Identifies a specific resource. You can specify a skill identifier, an in-skill product identifier, or a catalog identifier.
Format as a UUID.

String

No

requestFilters.resources[].type

Resource type.
Valid values: Skill, SkillCatalog, InSkillProduct, Import, Export.

String

No

requestFilters.requesters

Users that performed the operation.

Array of objects

No

requestFilters.requesters[].userId

List of LWA user IDs. For more details about user IDs, see Customer Profile. For details about how to retrieve the user ID, see Obtain Customer Profile Information.

Array of objects

Yes

requestFilters.startTime

Include audit logs with timestamps after this time, inclusive.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

requestFilters.endTime

Include audit logs with timestamps before this time, inclusive.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

requestFilters.httpResponseCodes

List of HTTP status codes.

Array of string

No

sortDirection

Set the sorting direction of the results as ascending or descending order.
Valid values: ASC, DESC.
Default: DESC

String

No

sortField

Sort the result on the specified field in alphabetical order.
Valid values: timestamp, operation, resource.id, resource.type, requester.userId, client.id, httpResponseCode.
Default: timestamp.

String

No

paginationContext

Wrapper for nextToken and maxResults. Include if iterating over a paginated response.

Object

No

paginationContext.nextToken

Identifies the next set of logs to return.

String

Yes

paginationContext.maxResults

Maximum number of results to return in the response.
Valid values: 1–200. Default: 50.

String

No

Response

A successful response returns HTTP 200 OK, along with the list of logs that match the filter criteria. If the number of results is too large, the response includes the paginationContext.nextToken. Use the token in your next Get audit logs request to get the next page of results.

On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The following example shows a response.

{
    "auditLogs": [{
            "xAmznRequestId": "a53cbaa5-f64b-11e7-94e4-e7de641ed24a",
            "timestamp": "2019-06-03T22:58:24.0Z",
            "operation": {
                "name": "associateSkillWithCatalog",
                "version": "v1"
            },
            "resources": [{
                    "id": "amzn1.ask.skill.1",
                    "type": "Skill"
                },
                {
                    "id": "amzn1.ask.cat.1",
                    "type": "Catalog"
                }
            ],
            "requester": {
                "userId": "amzn1.account.1"
            },
            "client": {
                "id": "client.id.1",
                "name": "ASK-CLI"
            },
            "httpResponseCode": 200
        },
        {
            "xAmznRequestId": "a53cbaa5-f64b-11e7-94e4-e7de641ed24a",
            "timestamp": "2019-06-03T22:58:24.0Z",
            "operation": {
                "name": "publishSkill",
                "version": "v1"
            },
            "resources": [{
                "id": "amzn1.ask.skill.1",
                "type": "Skill"
            }],
            "requester": {
                "userId": "amzn1.account.1"
            },
            "client": {
                "id": "client.id.1",
                "name": "ASK-CLI"
            },
            "httpResponseCode": 200
        }
    ],
    "paginationContext": {
        "nextToken": "someToken2"
    }
}

Response body properties

Property Description Type

auditLogs

List of audit logs for the specified vendor.

Array of objects

auditLogs.xAmznRequestId

Identifies the API request.
Formatted as a UUID.

String

auditLogs.timestamp

Date and time of the API request at the API endpoint.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

auditLogs.operation

Identifies the operation name and version.
For valid values, see Operation names and versions.

Object

auditLogs.operation.name

Name of the operation.

String

auditLogs.operation.version

Version of the operation.

String

auditLogs.resources

(Optional) List of resources or resource types affected by the request.

Array of objects

auditLogs.resources[].id

Identifies a specific resource.
Format as a UUID.

String

auditLogs.resources[].type

Identifies the resource type.
Valid values: Skill, SkillCatalog, InSkillProduct, Import, Export.

String

auditLogs.requester

User that performed the operation.

Object

auditLogs.requesters[].userId

LWA user ID. For more details about user IDs, see Customer Profile. For details about how to retrieve the user ID, see Obtain Customer Profile Information.

Array of objects

auditLogs.client

Identifies the developer tool that made the request.

Object

auditLogs.client.id

Identifier for the tool that the developer uses to manage their skills and skill-related resources. The id is the LWA client identifier associated with the LWA security profile. To view your client ID or create a new client ID, open the LWA console.
Format as a UUID. For actions performed on developer.amazon.com, set to Alexa Developer Console.

String

auditLogs.client.name

Name of the developer tool that made the request.

String

auditLogs.httpResponseCode

Resulting HTTP status code.

Integer

paginationContext

(Optional) Included if iterating over a paginated response.

Object

paginationContext.nextToken

Identifies the next set of logs to return.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of audit logs that match the specified filter criteria, or there are no results found for the given criteria.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Operation names and versions

The Audit Logs API supports the following REST API operation names and supported versions. Use these values in the requestFilters.operations[].name and requestFilters.operations[].version filters.

REST API Operation name Supported versions

Account Linking Management

getAccountLinkingInfo
deleteAccountLinkingInfo
updateAccountLinkingInfo

v0, v1
v1
v0, v1

Alexa-hosted Skill

generateCredentialsForAlexaHostedSkill
getAlexaHostedSkillMetadata
getAlexaHostedSkillUserPermissions

v1
v1
v1

Audit Logs

queryDevelopmentAuditLogs

v1

Catalog Content Upload

associateCatalogWithSkill
completeCatalogUpload
createCatalog
createCatalogUpload
getCatalog
getContentUploadById
generateContentUploadUrl
listCatalogsForVendor
listCatalogsForSkill
listUploadsForCatalog

v0
v0
v0
v0, v1
v0
v0, v1
v1
v0
v0
v0

In-Skill Product Management

createIspForVendor
disassociateIspWithSkill
getIspAssociatedSkills
getIspDefinition
getIspListForSkillId
getIspListForVendor
getIspSummary
resetEntitlementForProduct
updateIspForProduct

v1
v1
v1
v1
v1
v1
v1
v1
v1

Intent Request History

getUtteranceData
reviewUpdatesForIntentRequests

v1
v1

Interaction Model Catalog Management

createInteractionModelCatalog
createInteractionModelCatalogVersion
deleteInteractionModelCatalog
deleteInteractionModelCatalogVersion getInteractionModelCatalogUpdateStatus
getInteractionModelCatalogDefinition getInteractionModelCatalogValues listInteractionModelCatalogs
listInteractionModelCatalogVersion
getInteractionModelCatalogVersions
updateInteractionModelCatalog
updateInteractionModelCatalogVersion

v1
v1
v1
v1
v1
v1
v1
v1
v1
v1
v1
v1

Interaction Model Management

getInteractionModel
getInteractionModelMetadata
getInteractionModelStatus
setInteractionModel

v0, v1
v0, v1
v0
v0, v1

Metrics

getSkillMetrics

v1

NLU Annotation Set

createNluAnnotationSet
deleteNluAnnotationSet
getAnnotationsForNluAnnotationSet
getPropertiesForNluAnnotationSet
listNluAnnotationSets
setAnnotationsForNluAnnotationSet
setPropertiesForNluAnnotationSet

v1
v1
v1
v1
v1
v1
v1

NLU Evaluation

createNluEvaluation
getResultsForNluEvaluation
listNluEvaluations

v1
v1
v1

Skill Beta Testing

addTesterstoBetaTest
createBetaTest
endBetaTest
getBetaTest
getListOfTesters
removeTestersFromBetaTest
requestFeedbackFromTesters
sendReminderToTesters
updateBetaTest

v1
v1
v1
v1
v1
v1
v1
v1
v1

Skill Certification And Publishing

getCertificationReview
getCertificationsList
getSkillPublication
publishSkill
submitSkillForCertification
unpublishSkill
withdrawSkillFromCertification

v1
v1
v1
v1
v0, v1
v1
v0, v1

Skill Credentials

getSkillCredentials

v1

Skill Development Notifications

createSubscriberForDevelopmentEvents
createSubscriptionForDevelopmentEvents
deleteSubscriberForDevelopmentEvents
deleteSubscriptionForDevelopmentEvents
getSubscriberForDevelopmentEvents
getSubscriptionForDevelopmentEvents
listSubscribersForDevelopmentEvents
listSubscriptionsForDevelopmentEvents
setSubscriberForDevelopmentEvents
setSubscriptionForDevelopmentEvents

v0
v0
v0
v0
v0
v0
v0
v0
v0
v0

Skill Enablement

getSkillEnablementStatus
deleteSkillEnablement
setSkillEnablement

v1
v1
v1

Skill Invocation

invokeSkill

v0, v2

Skill Management

createSkillForVendor
deleteSkill
getSkillManifest
getSkillStatus
listSkills
listSkillsForVendor
updateSkill

v0, v1
v0, v1
v0, v1
v0
v1
v0
v0, v1

Skill Package Management

createExportRequestForSkill
createSkillPackage
createUploadUrl
getImportStatus
getStatusOfExportRequest
importSkillPackage

v1
v1
v1
v1
v1
v1

Skill Simulation

getSkillSimulation
simulateSkill

v0, v2
v0, v2

Skill SSL Certificates

getSSLCertificates
setSSLCertificates

v1
v1

Skill Validation

getSkillValidations
submitSkillValidation

v0
v0

Smart Home Evaluation

createCapabilityEvaluationForSmartHome
getCapabilityEvaluationForSmartHome
getCapabilityEvaluationResultsForSmartHome
listCapabilityEvaluationsForSmartHome
listCapabilityTestPlansForSmartHome

v1
v1
v1
v1
v1

Utterance Conflict Detection

getConflictDetectionJobStatusForInteractionModel
getUtteranceConflictsForSkill

v1
v1

Utterance Profiler

profileNlu

v1

Vendor Management

getVendorList

v0


Was this page helpful?

Last updated: Nov 17, 2023