ユーザーへの認可リクエスト

GET /oauth2/v1/authorize

概要

認可コード付与フローを開始するために、アプリケーションは Datadog の認可エンドポイントに GET リクエストを行います。これはユーザーを Datadog の認可付与フローにリダイレクトし、アプリケーションがリクエストしたスコープのリストと、ユーザーがアクセスを認可するためのプロンプトを表示する同意ページをレンダリングします。これはまた、リクエスト元の Datadog サイト を返します。

リクエスト

認可リクエストでは、アプリケーションは application/x-www-form-urlencoded フォーマットを用いて、URI のクエリコンポーネントに以下のパラメーターを追加することでリダイレクト URI を構築します。

リクエスト例

Datadog の同意ページをレンダリングするには、指定されたパラメーターでエンドポイントにユーザーをリダイレクトします。

https://app.datadoghq.com/oauth2/v1/authorize?redirect_uri=http://localhost:500/oauth_redirect&client_id=abcdefghijklmnopqrstuvwxyz_123456789&response_type=code&code_challenge=12345&code_challenge_method=S256

成功レスポンス

ユーザーがアクセスリクエストの許可に成功した場合、アプリケーションは認可コードを取得し、クエリコンポーネントに site パラメーターと同様に認可 code を指定してリダイレクト URI にユーザーをリダイレクトさせます。

エラーレスポンス

無効な redirect_uri や client_id が原因でリクエストが失敗した場合、ユーザーは指定した URI にリダイレクトされず、代わりに Datadog のエラーページが表示されます。

ユーザーが認可を拒否した場合、あるいはその他の理由でリクエストが失敗した場合、ユーザーはクエリーコンポーネントに error パラメーターを指定して redirect_uri へとリダイレクトされます。

認可コードを取得する

POST /oauth2/v1/authorize

概要

ユーザーが同意ページの Authorize ボタンをクリックすると、POST リクエストが自動的に認可エンドポイントに送られ、リクエストを検証して固有の認可コードが返されます。ユーザーは、クエリコンポーネントに認可コードパラメーターを指定して、アプリケーションの redirect_uri にリダイレクトされます。

リクエスト

アプリケーションは、この認可リクエストを行う必要はありません。このステップは、前のユーザー認可リクエストに対する応答であり、ユーザーがアプリケーションの認可に成功すると、Datadog によって自動的にリクエストされます。

アクセストークンの交換認可コード

POST /oauth2/v1/token

概要

認可リクエストから認可コードが返されると、アプリケーションはこのコードをアクセストークンやリフレッシュトークンに交換することができます。認可コードはリダイレクト URI から抽出され、Datadog の OAuth2 トークンエンドポイントに POST リクエストで送信されます。

Datadog のアクセストークンは、1 時間の TTL を持つ短命のトークンで、Datadog の API にアクセスを許可します。Marketplace OAuth クライアントの Refresh トークンは、有効期限がない長寿命なトークン (TTL は無限大) で、有効期限が切れるたびに新しいアクセストークンを自動的に取得するために使用されるトークンです。ユーザーが認可を取り消した場合、アプリケーションに対して新しいアクセストークンとリフレッシュトークンのセットを再認可する必要があります (リフレッシュトークンは期限切れとなります)。

リクエスト

アクセストークンのリクエストは、application/x-www-form-urlencoded 形式の POST リクエストの本文に、以下のパラメーターを指定して行います。

リクエスト例

アクセストークンのリクエストを行うには、この cURL コマンドを使用します。

curl -X POST \
    -d "grant_type=authorization_code&client_id=$CLIENT_ID
    client_secret=$CLIENT_SECRET&redirect_uri=$REDIRECT_URI
    code_verifier=$CODE_VERIFIER&code=$CODE" \
    "https://api.datadoghq.com/oauth2/v1/token"

成功レスポンス

アクセストークンのリクエストが有効で認可された場合、トークンレスポンスは、アクセストークンとリフレッシュトークンを HTTP レスポンスの本文に含めて、200 OK ステータスコードを返します。

エラーレスポンス

トークンのエンドポイントへのリクエストに失敗した場合は、アプリケーション上でユーザーを適切なエラーページにリダイレクトするなどして、アプリケーション側で処理する必要があります。

発行されたクライアントシークレットを持つ機密クライアントが client_secret パラメーターを指定せずにトークンリクエストを行うと、 401 Unauthorized ステータスコードが返されます。

不正なリクエストや無効な認可コードなど、その他の理由でトークンリクエストが失敗した場合、(特に指定がない限り) 400 Bad Request ステータスコードが error パラメーターとともに返されます。

トークンの取り消し

POST /oauth2/v1/revoke

概要

ユーザーは、いつでもアクセス権を取り消したり、トークンを更新したりすることができます。トークンを取り消すと、Datadog の API にアクセスするためにトークンを使用することができなくなります。トークンを取り消すには、アプリケーションから Datadog のトークン取り消しエンドポイントに POST リクエストを行います。

リクエスト

取り消しリクエストは、application/x-www-form-urlencoded 形式の HTTP POST リクエストの本文に、以下のパラメーターを指定して行います。

コード例

取り消しリクエストを行うには、この cURL コマンドを使用します。

curl -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d 'client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&token=$TOKEN_TO_REVOKE' \
    "https://api.datadoghq.com/oauth2/v1/revoke" \ 

成功レスポンス

トークンの取り消しに成功した場合、あるいは token パラメーターが無効な場合、取り消しレスポンスは 200 OK ステータスコードを返します。

エラーレスポンス

パラメーターが足りない、あるいは無効であるなど、何らかの理由でトークンリクエストに失敗した場合、(特に指定がない限り) 400 Bad Request ステータスコードが error パラメーターとともに返されます。

ユーザーに代わって API キーを作成する

POST /api/v2/api_keys/marketplace

概要

有効な OAuth アクセストークンまたはリフレッシュトークンを受け取ると、それを使って認可ユーザーの代わりに API キーを作成することができます。

このエンドポイントから作成される API キーは、OAuth を通して Datadog にデータを送信する唯一の方法です。API キーは Datadog の組織ごとに 1 つだけ存在でき、API キーの値は作成後に 1 度だけ表示されるので、それに従って保存してください。

このエンドポイントにアクセスするには、プライベートな API_KEYS_WRITE スコープが OAuth クライアントに関連付けられなければなりません。

リクエスト例

api_keys エンドポイントにリクエストを行うには、この cURL コマンドを使用します。

curl -X POST \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    "https://api.datadoghq.com/api/v2/api_keys/marketplace"

成功レスポンス

アクセスまたはリフレッシュトークンのリクエストが有効で認可された場合、以下が返されます。

{
  "data": {
    "type": "api_keys",
    "attributes": {
      "created_at": "2021-05-06T16:32:07.411970+00:00",
      "key": "ffffffffffffffffffffffffffffffff",
      "last4": "ffff",
      "modified_at": "2021-05-06T16:32:07.411970+00:00",
      "name": "Marketplace Key for App foobar"
    },
    "relationships": {
      "created_by": {
        "data": {
          "type": "users",
          "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl"
        }
      },
      "modified_by": {
        "data": {
          "type": "users",
          "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl"
        }
      }
    },
    "id": "abcdefgh-abcd-abcd-abcd-abcdefghijkl01234"
  }
}