リフレッシュトークン

規格への参照

前提条件

クライアントはデスクトップまたはモバイルアプリケーションです。

クライアントは Hub にサービスとして登録されています。つまり、クライアントはその serviceId と serviceSecret を「認識」しています。refreshToken を保存できるはずです。リフレッシュトークンを使用すると、エンドユーザーがオンラインでない場合でもリソースサーバーにアクセスできます。

クライアントアプリケーションは、Hub から refresh_token を取得しました。Hub は、認証コードおよびリソース所有者のパスワード資格情報許可フローのリフレッシュトークンの発行をサポートします。

アクセストークンのリフレッシュ

Hub がクライアントにリフレッシュトークンを発行した場合、クライアントは、HTTP リクエスト entity-body で UTF-8 の文字エンコードを使用して "application/x-www-form-urlencoded" 形式を使用して次のパラメーターを追加することにより、トークンエンドポイントにリフレッシュ要求を行います。

grant_type

必須。値は「refresh_token」に設定する必要があります。

refresh_token

必須。クライアントに発行されたリフレッシュトークン。

範囲

必須。アクセス要求の範囲: リソースサーバーに関連付けられた Hub サービスに登録されている ID のスペース区切りのリスト。例: クライアントが YouTrack の課題にアクセスしたい場合は、Hub の YouTrack サービスの ID を見つける必要があります。クライアントは、単一のアクセストークンで複数のリソースサーバーにアクセスできます。

注 : 要求されたスコープには、リソース所有者によって最初に付与されていないスコープを含めることはできません。省略した場合、リソース所有者によって最初に付与されたスコープと同じものとして扱われます。

リフレッシュトークンは通常、追加のアクセストークンを要求するために使用される長期的な資格情報であるため、リフレッシュトークンは発行されたクライアントにバインドされます。クライアントタイプが機密であるか、クライアントにクライアント資格情報が発行された（または他の認証要件が割り当てられた）場合、クライアントは Hub サーバーで RFC6749 で説明されています(英語)として認証する必要があります。

例: クライアントは、トランスポート層セキュリティを使用して次の HTTP リクエストを作成します（表示目的でのみ追加の改行を使用）。

            POST /api/rest/oauth2/token
            Host: hub.company.com
            Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
            Content-Type: application/x-www-form-urlencoded

            grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
        

許可サーバー（Hub）は次のことを行います。

機密クライアントにクライアント認証を要求する
クライアント認証が含まれている場合はクライアントを認証し、認証されたクライアントにリフレッシュトークンが発行されたことを確認します。
リフレッシュトークンを検証します。

リフレッシュトークンが有効で承認されている場合、Hub はアクセストークンを発行します。

リクエストの検証に失敗した場合、またはリクエストが無効な場合、Hub はエラー応答を返します。

Hub は、新しいアクセストークンとともに、新しいリフレッシュトークンを発行する場合があります。その場合、クライアントは古いリフレッシュトークンを破棄して、新しいリフレッシュトークンに置き換える必要があります。許可サーバー（Hub）は、クライアントに新しいリフレッシュトークンを発行した後、古いリフレッシュトークンを取り消す場合があります。新しいリフレッシュトークンが発行された場合、リフレッシュトークンのスコープは、クライアントが要求に含めたリフレッシュトークンのスコープと同じである必要があります。

アクセストークンリクエストに対する Hub からのエラー応答

エラー

以下からの単一の ASCII [USASCII] エラーコード:

invalid_request - 要求に必要なパラメーターが欠落しているか、サポートされていないパラメーター値（許可型以外）が含まれているか、パラメーターを繰り返しているか、複数の資格情報が含まれているか、クライアントを認証するために複数のメカニズムを使用しているか、不正な形式です。
invalid_client - クライアント認証に失敗しました（例: 不明なクライアント、クライアント認証が含まれていない、サポートされていない認証方法）。承認サーバーは、サポートされている HTTP 認証スキームを示す HTTP 401（未承認）ステータスコードを返す場合があります。クライアントが「Authorization」要求ヘッダーフィールドを介して認証を試みた場合、Hub サーバーは HTTP 401（Unauthorized）ステータスコードで応答し、クライアントが使用する認証スキームに一致する「WWW-Authenticate」応答ヘッダーフィールドを含めます。
invalid_grant - 提供された承認付与（承認コード、リソース所有者の資格情報など）またはリフレッシュトークンが無効であるか、期限切れであるか、取り消されているか、承認リクエストで使用されたリダイレクト URI と一致しないか、別のクライアントに発行されました。
unauthorized_client - 認証されたクライアントは、この許可付与タイプを使用することを許可されていません。
unsupported_grant_type - 認可付与タイプは、Hub ではサポートされていません。
invalid_scope - 要求されたスコープが無効、不明、不正な形式であるか、リソース所有者によって付与されたスコープを超えています。

error_description

発生したエラーをクライアント開発者が理解するのを支援するために使用される、追加情報を提供する人間が読める ASCII [USASCII] テキスト。

error_uri

エラーに関する追加情報をクライアント開発者に提供するために使用される、エラーに関する情報を含む人間が読める Web ページを識別する URI。

パラメーターは、「application/json」メディア型を使用して HTTP レスポンスのエンティティ本体に含まれます。パラメーターは、最上位の構造レベルで各パラメーターを追加することにより、JSON 構造にシリアル化されます。パラメーター名と文字列値は JSON 文字列として含まれています。数値は JSON 番号として含まれています。パラメーターの順序は重要ではなく、変化する可能性があります。

例:

            HTTP/1.1 400 Bad Request
            Content-Type: application/json;charset=UTF-8
            Cache-Control: no-store
            Pragma: no-cache

            {
            "error":"invalid_request"
            }
        

2026 年 4 月 16 日

YouTrack および Hub ヘルプの開発者ポータル