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

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:

  1. Create an LWA security profile and get an access token – For details about getting an access token, see Get an Access Token for SMAPI.

  2. 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.

  1. 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.
  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 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:

  1. Use SMAPI to call the Audit Log API.
  2. In the data retrieved for the audit logs, for each requester.userId, get the name and email address from your database.
  3. 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