User API Reference

The User API enables you to create, delete, and list representations of users.

API endpoint

In the request header, set Host to the following, depending on the region of your organization: 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).

Operations

The User API includes the following operations.

Operation HTTP Method and URI

Create user

POST /v1/auth/users

List users

GET /v1/auth/users

Delete user

DELETE /v1/auth/users/{userId}

Create user

Creates a user in the specified organization.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

None

US, CA

US, CA

US, CA

Request

To create a user, you make a POST request to the /v1/auth/users resource.

Request header example

Copied to clipboard.

POST /v1/auth/users HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

access token

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
  "organizationId": "amzn1.alexa.org.did.exampleId"
}

Request body parameters

Parameter Description Type Required

organizationId

ID of the organization to which to add the user. The format of the organization ID is amzn1.alexa.org.did.{id}.

String

Yes

Response

A successful response returns HTTP 201.

Response body example

The following example shows the body of a successful response.

Copied to clipboard.

{
  "userId": "amzn1.alexa.org.user.did.ABCGHLLKJKJHGHGHJ",
  "accessToken": "Atza|ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  "refreshToken": "Atzr|ABCDEFGHIJKLMNOPQRSTUVWXYZ"
}

Response body parameters

Parameter Description Type

userId

ID of the added user.

String

accessToken

Token that represents the added user. You use this token for subsequent API calls.

String

refreshToken

Refresh Token represents the added user. You use this token for refreshing the access token.

String

HTTP status codes

Status Description

201 OK

User created successfully.

400 INVALID_OPERATOR

Caller isn't part of the specified organization.

400 INVALID_ORGANIZATION_ID

Invalid organization ID.

401 UNAUTHORIZED

Authorization token is invalid, expired, or doesn't have access to the resource.

403 FORBIDDEN

Caller doesn't have permission to perform the operation.

429 TOO_MANY_REQUESTS

Caller has exceeded the permitted rate limit (specified number of requests per unit of time).

500 INTERNAL_SERVER_ERROR

Server has encountered an error.

503 SERVICE_UNAVAILABLE

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

List users

Lists the users of the specified organization.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

None

US, CA

US, CA

US, CA

Request

To list users, you make a GET request to the /v1/auth/users resource.

Request header example

Copied to clipboard.

GET /v1/auth/users?organizationId={organizationId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

access token

LWA token.

String

Yes

organizationId

ID of the organization to which to list the users. The format of the organization ID is amzn1.alexa.org.did.{id}.

String

Yes

maxResults

Maximum number of results to return in the response body. This value must be greater than zero and less than or equal to 10. The default value is 10. For details, see Handling Pagination in Query Results.

Number

No

nextToken

Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.

String

No

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200, along with a list of users.

Response body example

The following example shows the body of a successful response.

Copied to clipboard.

{
  "results": [
    {
      "userId": "amzn1.alexa.org.user.did.12345EXAMPLE"
    }
  ],
  "paginationContext": {
    "nextToken": null
  }
}

Response body parameters

Parameter Description Type

results[]

List of users returned in response to the query.

Array

results[].userId

The ID of the retrieved user. The format of the user ID is amzn1.alexa.org.user.did.{id}.

String

paginationContext.nextToken

Token to retrieve additional results if the results are paginated and there are more results.

String

HTTP status codes

Status Description

200 OK

 Successfully got the list of users for the specified organization ID.

400 INVALID_OPERATOR

Caller isn't part of the specified organization.

400 INVALID_ORGANIZATION_ID

Invalid organization ID.

400 INVALID_NEXT_TOKEN

Pagination token is invalid.

401 UNAUTHORIZED

Authorization token is invalid, expired, or doesn't have access to the resource.

403 FORBIDDEN

Caller doesn't have permission to perform the operation.

429 TOO_MANY_REQUESTS

User has exceeded the permitted rate limit (specified number of requests per unit of time).

500 INTERNAL_SERVER_ERROR

Server has encountered an error.

503 SERVICE_UNAVAILABLE

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

Delete user

Removes the specified user.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

None

US, CA

US, CA

US, CA

Request

To remove a user, you make a DELETE request to the /v1/auth/users/{userId} resource.

Request header example

Copied to clipboard.

DELETE /v1/auth/users/{userId} HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request header parameters

Parameter Description Type Required

access token

LWA token.

String

Yes

userId

ID for the user to remove. The format of the user ID is amzn1.alexa.org.user.did.{id}.

String

Yes

Request body example

The request has no body.

Response

A successful response returns HTTP 204.

Response body example

The response has no body.

HTTP status codes

Status Description

204 NO CONTENT

User deleted successfully.

400 INVALID_OPERATOR

Caller isn't part of the specified organization.

401 UNAUTHORIZED

Authorization token is invalid, expired, or doesn't have access to the resource.

403 FORBIDDEN

Caller doesn't have permission to perform the operation.

404 NO_SUCH_USER

User isn't found.

429 TOO_MANY_REQUESTS

User has exceeded the permitted rate limit (specified number of requests per unit of time).

500 INTERNAL_SERVER_ERROR

Server has encountered an error.

SERVICE_UNAVAILABLE

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

Was this page helpful?

Last updated: Nov 28, 2023