ユーザー管理REST APIリファレンス

ユーザー管理REST APIリファレンス

ユーザー管理REST APIを使用すると、Alexa Smart Properties（ASP）の組織内のユーザー表現を作成および削除したり、そのリストを取得したりできます。

APIエンドポイント

ユーザー管理APIのエンドポイントは、https://api.amazonalexa.comです。

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。詳細については、APIアクセスを管理するを参照してください。

操作

ユーザーAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

ユーザーを作成する

POST /v1/auth/users

ユーザーを削除する

DELETE /v1/auth/users/{userId}

ユーザーのリストを取得する

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

ユーザーを作成する

指定した組織に新しいユーザーを作成します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

なし

米国、カナダ

米国、カナダ

米国、カナダ

リクエスト

ユーザーを作成するには、/v1/auth/usersリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

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

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

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

リクエスト本文のプロパティ

パラメーター 説明 型 必須

organizationId

ユーザーを追加する組織を識別します。
amzn1.alexa.org.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

応答

正常に完了すると、HTTP 201 Createdと共に、ユーザーの認証情報が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

以下は、成功した応答の本文の例です。

クリップボードにコピーされました。

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

応答本文のプロパティ

パラメーター 説明 型

userId

追加したユーザーのID。

文字列

accessToken

追加したユーザーを表すトークン。
このトークンは後続のAPI呼び出しに使用します。

文字列

refreshToken

追加されたユーザーを表す更新トークン。
このトークンはアクセストークンを更新するために使用します。

文字列

HTTPステータスコード

ステータス 説明

201 Created

ユーザーの認証情報が応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_OPERATOR - 呼び出し元が指定された組織に所属していません。
  • INVALID_ORGANIZATION_ID - 組織IDが無効です。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

ユーザーを削除する

指定したユーザーを削除します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

なし

米国、カナダ

米国、カナダ

米国、カナダ

リクエスト

ユーザーを削除するには、/v1/auth/users/{userId}リソースに対してDELETEリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

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

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

userId

パス

削除するユーザーのID。
amzn1.alexa.user.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

ユーザーが正常に削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_OPERATOR - 呼び出し元が指定された組織に所属していません。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

ユーザーのリストを取得する

指定した組織のユーザーのリストを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

なし

米国、カナダ

米国、カナダ

米国、カナダ

リクエスト

ユーザーのリストを取得するには、/v1/auth/usersリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

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}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

organizationId

クエリ

組織でフィルタリングします。
amzn1.alexa.org.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

×

maxResults

クエリ

応答で返される結果の最大数。
有効な値は 1～10です。デフォルト値は 10です。

整数

×

nextToken

クエリ

前回の応答で受け取ったトークン。
ページ分割された応答の反復処理を行う場合に含めます。

文字列

×

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、指定された組織のユーザーのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

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

応答本文のプロパティ

プロパティ 説明 型

results

指定された組織のユーザーのリスト。
このリストには、maxResultsで指定された最大数までの任意の数の要素が含まれる可能性があります。空になる場合もあります。

オブジェクトの配列

results[].userId

取得されたユーザーのID。
amzn1.alexa.user.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は、後続のリクエストで、このリクエストと同じフィルターパラメーターと共に使用します。
結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定された組織のユーザーIDのリストが応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_OPERATOR - 呼び出し元が指定された組織に所属していません。
  • INVALID_ORGANIZATION_ID - 組織IDが無効です。
  • INVALID_NEXT_TOKEN - ページ分割トークンが無効です。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

このページは役に立ちましたか？

最終更新日: 2025 年 07 月 14 日