User Management REST API Reference

Use the User Management REST API to create, delete, and list representations of users in your Alexa Smart Properties (ASP) organization.

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). For details, see Manage API Access.

Operations

The User API includes the following operations.

Operation HTTP Method and URI

Create user

POST /v1/auth/users

Delete user

DELETE /v1/auth/users/{userId}

List users

GET /v1/auth/users?organizationId={organizationId}&maxResults={maxResults}&nextToken={nextToken}

Create user

Create a new 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 path and 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 path and header parameters

Parameter Located in Description Type Required

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

Copied to clipboard.

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

Request body properties

Parameter Description Type Required

organizationId

Identifies the organization to which to add the user.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.org.did.{id}.

String

Yes

Response

A successful response returns HTTP 201 Created, along with the user credentials. On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.

Response body example

The following example shows the body of a successful response.

Copied to clipboard.

{
  "userId": "amzn1.alexa.org.user.did.1",
  "accessToken": "someToken.1",
  "refreshToken": "someToken.2"
}

Response body properties

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 that represents the added user.
You use this token to refresh the access token.

String

HTTP status codes

Status Description

201 Created

Response body contains the user credentials.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

The response might include one of the following errors types and messages:

  • INVALID_OPERATOR – Caller isn't part of the specified organization.
  • INVALID_ORGANIZATION_ID – Invalid organization ID.

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

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You 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.

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 path and 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 path and header parameters

Parameter Located in Description Type Required

userId

Path

ID of the user to delete.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.user.did.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

User deleted successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

The response might include one of the following errors types and messages:

  • INVALID_OPERATOR – Caller isn't part of the specified organization.

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

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You 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.

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 path and 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 path and header parameters

Parameter Located in Description Type Required

organizationId

Query

Filter on the organization.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.org.did.{id}.

String

No

maxResults

Query

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

Integer

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of users for the specified organization. On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.

Response body example

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

Response body properties

Property Description Type

results

List of users under the specified organization.
This list might be empty or contain any number of elements up to maxResults.

Array of objects

results[].userId

ID of the retrieved user.
Formatted as Amazon Common Identifier (ACI), amzn1.alexa.user.did.{id}.

String

paginationContext

Indicates whether there are more results to return.

Object

paginationContext.nextToken

Included when the response is truncated.
Use this value in a subsequent request with the same filter parameters as this request.
If no more results, nextToken is null.

String

HTTP status codes

Status Description

200 OK

Response body contains the list of user IDs for the specified organization.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

The response might include one of the following errors types and messages:

  • INVALID_OPERATOR – Caller isn't part of the specified organization.
  • INVALID_ORGANIZATION_ID – Invalid organization ID.
  • INVALID_NEXT_TOKEN – Pagination token is invalid

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

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You 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.

Was this page helpful?

Last updated: Oct 31, 2024