User API Reference

---

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

API endpoint

The endpoint of the User API 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).

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	Residential	Senior Living	Core
None	US, CA	None	US, CA	US, CA

Request

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

Request header example

Request header parameters

Parameter	Description	Type	Required
access token	LWA token.	String	Yes

Request body example

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.

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	Residential	Senior Living	Core
None	US, CA	None	US, CA	US, CA

Request

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

Request header example

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.

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	Residential	Senior Living	Core
None	US, CA	None	US, CA	US, CA

Request

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

Request header example

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.

Related topics

• Get Started with Alexa Smart Properties Core APIs
• REST API Reference
• About Alexa Smart Properties

---

Last updated: Apr 06, 2023