Audit Logs API
Use the Audit Logs API to get logs that show the history of calls made to the Skill Management API (SMAPI). The logs include information about each operation including the timestamp, response code, and source.
Consider the following ways of using the Audit Logs API:
- As an independent developer building an Alexa skill, use the Audit Logs API to get logs of all operations related to your skill.
- As a tool-builder, in the developer tool that you build and distribute, give the user a way to view the logs of operations performed in the tool by the same user. The Audit Logs API limits the logs to the user-specific history of operations performed by the same developer tool.
The logs do not show any information about customer actions and only show operations performed by skill builders or developer tools.
- Workflow for an independent developer
- Workflow for a tool-builder
- Endpoint and header
- Request
- Response
- Operation names and supported versions
Workflow for an independent developer
The following are prerequisites for getting audit logs as an independent developer:
- Amazon developer account – To create Alexa skills and perform the operations reported in the audit logs, you need an Amazon developer account. If you don't already have an account, sign up at developer.amazon.com. Every Amazon developer account has a vendor ID. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.
- ASK CLI – ASK CLI is a tool that you can use to develop and configure Alexa skills by using the command line. You don't need the ASK CLI if you simply want to get audit logs for skills that you create for an organization or through an organization's tool. However, if you're an independent developer or organization, you might need the ASK CLI to get an access token that you use when you call SMAPI to get audit logs for yourself. To download and install the ASK CLI, see Quick Start: Alexa Skills Kit Command Line Interface (ASK CLI).
As an independent developer, use the following workflow to get the audit logs:
-
Create an LWA security profile and get an access token – For details about getting an access token, see Get an Access Token for SMAPI.
-
Use the access token to request audit logs through SMAPI – Specify the endpoint and filters for the operations that you want to show in the audit logs. The logs include the operations performed across all of 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.
- In the tool, authenticate the developer user through the standard LWA authentication flow to get an access token for the user. For more details about getting an access token, see Get an Access Token for SMAPI.
- 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.
- In the database that you maintain for the tool, save the user identifier, name, and email address.
Then, when the developer uses the tool to request audit logs, do the following to get the logs and show the name and email address of the user in the logs:
- Use SMAPI to call the Audit Log API.
- In the data retrieved for the audit logs, for each
requester.userId
, get the name and email address from your database. - When displaying the audit logs in the tool, instead of showing the user identifer, show the name and email address of the user.
Endpoint and header
The endpoint is https://api.amazonalexa.com
. Each API request must have an Authorization
header whose value should be the access token retrieved from Login with Amazon.
Request
Request body structure
POST /v1/developmentAuditLogs/query
{
"vendorId": "{vendorId}",
"requestFilters": {
"resources": [
{
"id": "amzn1.ask.skill.1234",
"type": "Skill"
}
],
"requesters": [
{
"userId": "amzn1.account.LWAUserId"
}
],
"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": "Vxjbbbbbbbbaa",
"maxResults": 2
}
}
Request parameters
Parameter | Required | Description | Type |
---|---|---|---|
vendorId |
Yes | Unique vendor identifier. | String |
resources[*].id |
No | Identifier of a specific resource, for example amzn1.skill.1234 . You can specify a skill identifier, an in-skill product identifier, or a catalog identifier. |
String |
resources[*].type |
No | Specify Skill , InSkillProduct , SkillCatalog , Export , or Import . |
String |
requesters[*].userId |
No | List of customer identifiers. A customer identifier is an LWA user identifier. For more details about customer identifiers, see Customer Profile. For details about how to retrieve the customer identifier, see Obtain Customer Profile Information. | String |
clients[*].id |
No | List of client identifiers for your developer tool. The client identifier is the LWA client identifier associated with the LWA security profile. To view your client identifiers or create a new client identifier, open the LWA console. For actions performed on developer.amazon.com, the client identifier is Alexa Developer Console . If you are a tool-builder, you don't need to specify the client identifier because the audit logs already filter to show only the operations performed by your client. As a tool-builder, specifying a different client identifier would cause an error. |
String |
httpResponseCodes[*] |
No | List of strings specifying the response codes on which to filter. | String |
operations[*].name |
No, but required if you specify operations[*].version |
List of names of the operations on which to filter, for example publishSkill . For details about operation names, see Operation names and supported versions. |
String |
operations[*].version |
No, but required if you specify operations[*].name |
Version of the operation on which to filter, for example v1 . For details about the supported versions, see Operation names and supported versions. |
String |
startTime |
No | Timestamp in ISO 8601 format that specifies that you want to display only the operations that occurred on or after the specified time. | String |
endTime |
No | Timestamp in ISO 8601 format that specifies that you want to display only the operations that occurred on or before the specified time. | String |
sortField |
No | Field by which to sort the data in the log. Specify timestamp , client.id , operation.name , resource.id , resource.type , httpResponseCode , or requester.userId . The default value is timestamp . |
String |
sortDirection |
No | Specifies the sort direction. Specify ASC for ascending or DESC for descending. The default value is DESC . |
String |
nextToken |
No | Token for displaying the next page of results. | String |
maxResults |
No | Maximum count of items to be returned. The default count is 50. The value must be at least 1 and no more than 200. | String |
Response
Response body structure
{
"paginationContext": {
"nextToken": "VXjbbbbbbbbb"
},
"auditLogs": [
{
"xAmznRequestId": "a53cbaa5-f64b-11e7-94e4-e7de641ed24a",
"timestamp": "2019-06-03T22:58:24.0Z",
"operation": {
"name": "associateSkillWithCatalog",
"version": "v1"
},
"resources": [
{
"id": "amzn1.ask.skill.1234",
"type": "Skill"
},
{
"id": "amzn1.ask.cat.1234",
"type": "Catalog"
}],
"requester": {
"userId": "amzn1.oauth.LWAUserId"
},
"client": {
"id": "amzn1.application-oa2-client.aad322b5faab44b980c8f87f94fbac56",
"name": "Alexa Skills Kit Command Line Interface"
},
"httpResponseCode": 200
},
{
"xAmznRequestId": "a53cbaa5-f64b-11e7-94e4-e7de641ed24a",
"timestamp": "2019-06-03T22:58:24.0Z",
"operation": {
"name": "publishSkill",
"version": "v1"
},
"userAgent": "cfn-skill-handler",
"resources": [
{
"id": "amzn1.ask.skill.1234",
"type": "Skill"
}],
"requester": {
"userId": "amzn1.oauth.LWAUserId"
},
"client": {
"id": "amzn1.application-oa2-client.aad322b5faab44b980c8f87f94fbac56"
"name": "ASK-CLI"
},
"httpResponseCode": 200
}
]
}
Response body fields
Field | Required | Description |
---|---|---|
nextToken |
No | Encoded nextToken to fetch the next set of results, if the response was truncated. |
xAmznRequestId |
Yes | Universally unique identifier corresponding to the operation in the audit log. |
timestamp |
Yes | Time that that operation in the audit log occurred. The timestamp reflects the server-side recording of the time. |
operation.name |
Yes | External-facing name for the operation in the audit log. For details about operation names, see Operation names and supported versions. |
operation.version |
Yes | Version of the operation, for example v0, v1, v2, and so on. For details about supported versions, see Operation names and supported versions. |
resources[*].id |
No | Identifier of the resource upon which the operation occurred. |
resources[*].type |
No | Type of resource upon which the operation occurred. |
requester.userId |
Yes | LWA user identifier. |
client.id |
Yes | Client identifier of the tool that called SMAPI on behalf of the customer. |
client.name |
Yes | Client name of the tool that called SMAPI on behalf of the customer. |
httpResponseCode |
Yes | Integer representing the HTTP status code returned for an operation in the audit log. |
Response codes
The following are possible response codes to a request for audit logs.
Status code | Description |
---|---|
200 SUCCESS |
The call succeeded, or there are no results found for the given search. |
400 BAD REQUEST |
The input is not valid, for example the client identifier is incorrectly formatted, or the caller provided a NextToken that is not valid. |
401 NOT AUTHORIZED |
The customer access token is not valid. |
403 FORBIDDEN |
The customer does not have permissions for the specified vendor, or the developer tool attempted to get information about a client identifier other than the current client. |
404 NOT FOUND |
Vendor not found. |
429 TOO MANY REQUESTS |
The caller exceeded the limit on frequency of requests. |
500 INTERNAL SERVER ERROR |
The operation failed because of an issue within the service. |
Operation names and supported versions
The following table shows the supported values for operations[*].name
and operations[*].version
.
Category | Operation name | Supported version |
---|---|---|
Account Linking Management | getAccountLinkingInfo |
v0, v1 |
updateAccountLinkingInfo |
v0, v1 | |
deleteAccountLinkingInfo |
v1 | |
Audit Logs | queryDevelopmentAuditLogs |
v1 |
Catalog Content Upload | associateCatalogWithSkill |
v0 |
completeCatalogUpload |
v0 | |
createCatalogUpload |
v0, v1 | |
getContentUploadById |
v0, v1 | |
generateContentUploadUrl |
v1 | |
createCatalog |
v0 | |
getCatalog |
v0 | |
listCatalogsForVendor |
v0 | |
listCatalogsForSkill |
v0 | |
listUploadsForCatalog |
v0 | |
Intent Request History | getUtteranceData |
v1 |
reviewUpdatesForIntentRequests |
v1 | |
Interaction Model Management | getInteractionModel |
v0, v1 |
getInteractionModelVersion |
v1 | |
listInteractionModelVersions |
v1 | |
getInteractionModelMetadata |
v0, v1 | |
setInteractionModel |
v0, v1 | |
getInteractionModelStatus |
v0 | |
In-Skill Product Management | createIspForVendor |
v1 |
getIspDefinition |
v1 | |
disassociateIspWithSkill |
v1 | |
updateIspForProduct |
v1 | |
getIspSummary |
v1 | |
getIspListForVendor |
v1 | |
getIspAssociatedSkills |
v1 | |
getIspListForSkillId |
v1 | |
resetEntitlementForProduct |
v1 | |
Metrics | getSkillMetrics |
v1 |
Slot Type in Multiple Skills | createSlotTypeForInteractionModel |
v1 |
getSlotTypeForInteractionModel |
v1 | |
updateSlotTypeForInteractionModel |
v1 | |
listSlotTypesForInteractionModel |
v1 | |
deleteSlotTypeForInteractionModel |
v1 | |
createSlotTypeVersionForInteractionModel |
v1 | |
getSlotTypeVersionForInteractionModel |
v1 | |
getSlotTypeBuildStatusForInteractionModel |
v1 | |
updateSlotTypeVersionForInteractionModel |
v1 | |
listSlotTypeVersionsForInteractionModel |
v1 | |
deleteSlotTypeVersionForInteractionModel |
v1 | |
Reference-Based Catalog Management | createInteractionModelCatalog |
v1 |
createInteractionModelCatalogVersion |
v1 | |
getInteractionModelCatalogUpdateStatus |
v1 | |
listInteractionModelCatalogs |
v1 | |
listInteractionModelCatalogVersions |
v1 | |
getInteractionModelCatalogVersion |
v1 | |
getInteractionModelCatalogDefinition |
v1 | |
getInteractionModelCatalogValues |
v1 | |
updateInteractionModelCatalog |
v1 | |
updateInteractionModelCatalogVersion |
v1 | |
deleteInteractionModelCatalog |
v1 | |
deleteInteractionModelCatalogVersion |
v1 | |
Skill Certification And Publishing | submitSkillForCertification |
v0, v1 |
withdrawSkillFromCertification |
v0, v1 | |
getCertificationReview |
v1 | |
getCertificationsList |
v1 | |
unpublishSkill |
v1 | |
publishSkill |
v1 | |
getSkillPublication |
v1 | |
Skill Credentials | getSkillCredentials |
v1 |
Skill Enablement | getSkillEnablementStatus |
v1 |
setSkillEnablement |
v1 | |
deleteSkillEnablement |
v1 | |
Skill Management | getSkillManifest |
v0, v1 |
createSkillForVendor |
v0, v1 | |
updateSkill |
v0, v1 | |
getSkillStatus |
v0 | |
listSkillsForVendor |
v0 | |
listSkills |
v1 | |
deleteSkill |
v0, v1 | |
Skill Package Management | createUploadUrl |
v1 |
createSkillPackage |
v1 | |
importSkillPackage |
v1 | |
createExportRequestForSkill |
v1 | |
getImportStatus |
v1 | |
getStatusOfExportRequest |
v1 | |
Smart Home Evaluation | listCapabilityTestPlansForSmartHome |
v1 |
createCapabilityEvaluationForSmartHome |
v1 | |
listCapabilityEvaluationsForSmartHome |
v1 | |
getCapabilityEvaluationForSmartHome |
v1 | |
getCapabilityEvaluationResultsForSmartHome |
v1 | |
Vendor Management | getVendorList |
v0 |
Alexa-hosted Skill | getAlexaHostedSkillMetadata |
v1 |
generateCredentialsForAlexaHostedSkill |
v1 | |
getAlexaHostedSkillUserPermissions |
v1 | |
Skill Validation | submitSkillValidation |
v0 |
getSkillValidations |
v0 | |
Skill Invocation | invokeSkill |
v0, v2 |
Skill Simulation | simulateSkill |
v0, v2 |
getSkillSimulation |
v0, v2 | |
Skill Beta Testing | getBetaTest |
v1 |
createBetaTest |
v1 | |
updateBetaTest |
v1 | |
endBetaTest |
v1 | |
getListOfTesters |
v1 | |
addTesterstoBetaTest |
v1 | |
removeTestersFromBetaTest |
v1 | |
sendReminderToTesters |
v1 | |
requestFeedbackFromTesters |
v1 | |
Skill Development Notifications | createSubscriberForDevelopmentEvents |
v0 |
createSubscriptionForDevelopmentEvents |
v0 | |
deleteSubscriberForDevelopmentEvents |
v0 | |
deleteSubscriptionForDevelopmentEvents |
v0 | |
getSubscriberForDevelopmentEvents |
v0 | |
getSubscriptionForDevelopmentEvents |
v0 | |
listSubscribersForDevelopmentEvents |
v0 | |
listSubscriptionsForDevelopmentEvents |
v0 | |
setSubscriberForDevelopmentEvents |
v0 | |
setSubscriptionForDevelopmentEvents |
v0 | |
Utterance Profiler | profileNlu |
v1 |
NLU Evaluation | createNluEvaluation |
v1 |
listNluEvaluations |
v1 | |
getResultsForNluEvaluation |
v1 | |
createNluAnnotationSet |
v1 | |
setAnnotationsForNluAnnotationSet |
v1 | |
setPropertiesForNluAnnotationSet |
v1 | |
listNluAnnotationSets |
v1 | |
getAnnotationsForNluAnnotationSet |
v1 | |
getPropertiesForNluAnnotationSet |
v1 | |
deleteNluAnnotationSet |
v1 | |
Utterance Conflict Detection | getUtteranceConflictsForSkill |
v1 |
getConflictDetectionJobStatusForInteractionModel |
v1 | |
Skill SSL Certificates | setSSLCertificates |
v1 |
getSSLCertificates |
v1 | |
Private Skill Distribution | setPrivateDistributionAccountId |
v0 |
deletePrivateDistributionAccountId |
v0 | |
listPrivateDistributionAccounts |
v0 |
Last updated: Mar 30, 2022