認証と認可

API Key

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

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

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

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

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

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

GET

/OAuth2AccessRequest.action

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

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

POST

/api/v2/oauth2/token

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

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

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

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" 
}

トークンエンドポイントから取得したアクセストークンを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

/api/v2/oauth2/token

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

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" 
}