認証と認可

API Key

リクエストにユーザーごとに発行された API キーを付加して認証する方式です。 リソースへのアクセス時に、発行された API キーをクエリパラメーター “apiKey” またはリクエストヘッダー “Backlog-API-Key” として付加することで認証が行えます。

リクエスト例

https://xx.backlog.jp/api/v2/users/myself?apiKey=abcdefghijklmn

URLがbacklog.comの場合は次のようになります。

https://xx.backlog.com/api/v2/users/myself?apiKey=abcdefghijklmn

リクエスト例（リクエストヘッダー）

API キーはクエリパラメーターの代わりにリクエストヘッダー “Backlog-API-Key” で送信することもできます。

GET /api/v2/users/myself
HTTP/1.1
Host: xx.backlog.jp (URLがbacklog.comの場合はxx.backlog.comになります)
Backlog-API-Key: abcdefghijklmn

OAuth 2.0

OAuth2認可フレームワーク(RFC 6749)で定められた認可コードによる認可(Authorization Code Grant)を使用してAPIにアクセスすることができます。

ここで使用するclient_idとclient_secretを取得するには、Backlog Developer サイトでアプリケーション登録を行ってください。

認可リクエスト

メソッド

GET

URL

/OAuth2AccessRequest.action

認可エンドポイントです。 ユーザからの許可が得られた場合、redirect_uriに認可コードを含めてリダイレクトを行います。

クエリパラメーター

名前	型	説明
response_type (必須)	string	値は”code”で固定
client_id (必須)	string
redirect_uri (必須)	string	開発アプリケーション ページで設定したものと同じUri
state	string

アクセストークンリクエスト

メソッド

POST

URL

/api/v2/oauth2/token

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

リクエストパラメーター

Content-Type:application/x-www-form-urlencoded

パラメーター名	型	内容
grant_type (必須)	string	値は”authorization_code”で固定
code (必須)	string	認可エンドポイントのリダイレクトから取得した認可コード
redirect_uri (必須)	string	開発アプリケーション ページで設定したものと同じUri
client_id (必須)	string
client_secret (必須)	string

レスポンス例

ステータスライン / レスポンスヘッダ

HTTP/1.1 200 OK
Content-Type:application/json;charset=utf-8

レスポンスボディ

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"YOUR_REFRESH_TOKEN"
}

アクセストークンを使用したAPIアクセス

トークンエンドポイントから取得したアクセストークンをAuthorizationヘッダーに含めてAPIを呼び出すことができます

GET /api/v2/space
HTTP/1.1
Host: example.backlog.jp (URLがbacklog.comの場合はexample.backlog.comになります)
Authorization: Bearer YOUR_ACCESS_TOKEN

認証エラーが発生した場合、ステータスコード401を返却します。 エラーの詳細はレスポンスのWWW-Authenticateヘッダーを確認して下さい。

• アクセストークンが間違っている場合

"Bearer error="invalid_token", error_description="The access token is invalid"

• アクセストークンの有効期限切れの場合

"Bearer error="invalid_token", error_description="The access token expired"

アクセストークンの更新

アクセストークンは新規に生成されてから3600秒（1時間）で有効期限切れになります。リフレッシュトークンを使ってトークンエンドポイントから有効なアクセストークンを取得することができます。

メソッド

POST

URL

/api/v2/oauth2/token

リクエストパラメーター

Content-Type:application/x-www-form-urlencoded

パラメーター名	型	内容
grant_type (必須)	string	値は”refresh_token”で固定
client_id (必須)	string
client_secret (必須)	string
refresh_token (必須)	string

レスポンス例

ステータスライン / レスポンスヘッダ

HTTP/1.1 200 OK
Content-Type:application/json;charset=utf-8

レスポンスボディ

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"YOUR_REFRESH_TOKEN"
}

権限と制限

API を呼び出せるかどうかは、そのユーザーの「権限」と「制限」の組み合わせで決まります。それぞれで何ができるかはユーザーの権限を参照してください。

権限

ユーザーがスペースやプロジェクトに対して持つ役割です。

• 管理者
• プロジェクト管理者
• 一般ユーザー
• ゲスト

API のページでは、上記の 4 つすべてを含むことを「すべての権限」と表記します。

制限

権限の範囲内で、操作できることをさらに狭める設定です。「一般ユーザー」と「ゲスト」に対して設定できます。

• 制限なし
• 課題の登録のみ
• 課題の閲覧のみ

「実行可能な権限」の読み方

各 API のページには、その API を呼び出せるユーザーが「実行可能な権限」として記載されています。記載のしかたには、以下のパターンがあります。

権限と制限が併記されている場合

権限 と 制限 の欄それぞれについて、記載された値のいずれかに該当するユーザーが呼び出せます。複数の値が記載されている場合は、いずれか1つに該当すればよいです。

例えば添付ファイルの送信では、権限に「すべての権限」、制限に「課題の登録のみ」と「制限なし」が記載されています。この API は、権限は問わず、制限が「課題の登録のみ」または「制限なし」のいずれかであるユーザーが呼び出せます。制限が「課題の閲覧のみ」のユーザーは呼び出せません。

権限だけが記載されている場合

「管理者」「プロジェクト管理者」のように権限だけが記載されている場合は、その権限を持つユーザーが呼び出せます。複数の値が記載されている場合は、いずれか1つに該当すればよいです。

「すべての権限」とだけ記載されている場合

権限も制限も問わず、すべてのユーザーが呼び出せます。

権限 の欄に「すべての権限」と記載されている場合とは意味が異なります。権限 の欄にある場合は権限を問わないという意味で、呼び出せる範囲は 制限 の欄によって絞られます。単独で記載されている場合は制限による絞り込みがありません。