認証(APIkey・OAuth)

概要

Jooto API は　API keyと OAuth2.0による２種類の認証方法でご利用いただくことが可能です。
各認証方法の利用においては、ユーザーのJootoの管理画面上であらかじめ設定を行う必要があります。
認証方法により設定方法が異なりますので、下記をご参考に認証を行ってください。

Jooto API へのリクエスト時に、リクエストヘッダーに API キーを付与して認証する方式です。
API キーの発行は、組織の設定ページから行えます。

（１）組織の設定ページより「APIキー」の設定を選択し、発行済みAPIキー一覧ページにアクセス

（２）新規のAPIキー発行には、画面右上の「APIキーを追加」を選択

（３）任意で利用する目的などを説明欄にご記載いただき、Jooto API利用規約（https://www.jooto.com/api-terms/）に同意にチェックを入れて、「追加」をご選択ください。

（４）発行済みのAPIキー一覧にAPIキーが発行されます。対象をクリックしてAPIキーを確認可能です。

※組織の管理者はAPIキーを管理でき、発行されている全てのAPIキーの編集・削除が可能です。

APIキーはヘッダー名を「X-Jooto-Api-Key」にて指定します。
以下は組織の詳細情報の取得API へのリクエスト時に、上記のJooto管理画面にて発行した
「hogehoge」という値をAPI キーに指定して認証する例です。

GET /organizations
HTTP/1.1
Host: app.jooto.com
X-Jooto-Api-Key: hogehoge（APIキーの値）

OAuth2.0 認可フレームワーク(RFC 6749)で定められた認可コードによる認証方式(Authorization Code Grant)を使用して API にアクセスする方式です。

OAuth2.0 方式での認証を利用するためには、組織の設定ページからアプリケーションを登録し、「Client Id」と「Client Secret」を取得する必要があります。

（１）組織の設定ページより「アプリケーション」の設定を選択し、アプリ一覧ページにアクセス

（２）新規の認証先アプリ登録には、画面右上の「アプリケーションを追加」を選択

（３）連携先アプリ名とリダイレクトURI、任意で説明欄にご記載いただき、Jooto API利用規約（https://www.jooto.com/api-terms/）に同意にチェックを入れ、「追加」をご選択ください。

（４）登録済みのアプリ一覧にアプリが追加されます。
対象をクリックして、「Client Id」と「Client Secret」を確認可能です。

※OAuth2.0のアプリケーション管理は組織の管理者のみ行うことができます。

アプリケーションの認可には下記のエンドポイントを使用します。

エンドポイントから取得されるアクセス許可確認ページのURLより、ユーザーがアクセスを許可すると、指定されたリダイレクトURIに認可コードを含めてリダイレクトします。

GET https://app.jooto.com/oauth2/login

<リクエストパラメーター>

値	型	説明
client_id	string	作成したアプリケーションの client_id
redirect_uri	string	作成したアプリケーションで指定したリダイレクト URI
response_type	string	値は必ず”code”を指定する
state	string	ランダムな文字列を指定する
organization_id	number	リソースを取得したい組織の ID

組織のIDの確認方法はJootoにログインいただき、プロジェクトリストの画面にてURLをご確認いただき、「https://app.jooto.com/boards?organization_id=XXXXX」より「XXXXX」部分が組織IDです。

＜ユーザーのアクセス許可確認画面＞

認可エンドポイントのリダイレクトから取得した認可コードを使用して、
下記のエンドポイントから有効なアクセストークン及びリフレッシュトークンを取得できます。

POST /oauth2/token

<リクエストパラメーター>

値	型	説明
code	string	認可エンドポイントのリダイレクトから取得した認可コード
client_id	string	作成したアプリケーションの client_id
client_secret	string	作成したアプリケーションの client_secret
redirect_uri	string	作成したアプリケーションで指定したリダイレクト URI
grant_type	string	値は必ず”authorization_code” を指定する

<レスポンス例（json）>

{
  "access_token": "アクセストークンの値",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "リフレッシュトークンの値"
}

取得したアクセストークンをリクエスト時に Authorization ヘッダーに指定することにより、Jooto API の各エンドポイントを利用できます。

GET /organizations/1
HTTP/1.1
Host: app.jooto.com
Authorization: Bearer "アクセストークンの値"

アクセストークンは生成から 3600 秒(1 時間)で失効します。トークン取得エンドポイントから取得したリフレッシュトークンを使って、新しいアクセストークンを取得できます。

POST /oauth2/token

値	型	説明
client_id	string	作成したアプリケーションの client_id
client_secret	string	作成したアプリケーションの client_secret
refresh_token	string	トークン取得エンドポイントから取得したリフレッシュトークン
grant_type	string	値は必ず”refresh_token” を指定する

<レスポンス例（json）>

{
  "access_token": "アクセストークンの値",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "リフレッシュトークンの値"
}