OAuth 2.0 Authorization
To access YouTrack resources with the REST API using OAuth 2.0, you need to log in, authorize, and obtain an access token for YouTrack. Authorization is provided by the Hub service.
We only recommend that you use OAuth 2.0 when your application requires client-side authentication. Otherwise, you're better off using token-based authorization. For more information, see Permanent Token Authorization.
If your YouTrack Standalone installation is connected to an external Hub service, then you can use any OAuth 2.0 authorization flow that is supported by Hub. The built-in Hub service only supports implicit authorization grants. External Hub installations support a wider range of authorization methods. For details, refer to the Hub documentation.
To use implicit OAuth 2.0 authorization, your client application must be publicly available over the internet. Such applications are usually written in JavaScript and run in a web browser.
Endpoints
The built-in Hub service uses the following OAuth 2.0 endpoints:
Endpoint | URL |
---|---|
Authentication | <Hub service URL>/api/rest/oauth2/auth |
Token | <Hub service URL>/api/rest/oauth2/token |
The <Hub service URL>
is the access point for the Hub service in your network environment. For YouTrack Standalone installations, the service is accessible from your YouTrack Base URL appended with the path /hub
. For example, www.company-youtrack.com/hub
.
You can find the Base URL for your installation on the Global Settings page. For more information, see System.
Implicit Authorization
YouTrack supports OAuth 2.0 authorization with implicit authorization as specified in the OAuth 2.0 Authorization Framework.
To obtain an access token from YouTrack, you need to provide values for the following parameters:
Requests
To start authentication, redirect the browser to the authorization endpoint:
${Hub service URL}/api/rest/oauth2/auth?response_type=token&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client service ID}&scope=${Scope}
Example:
https://www.company-youtrack.com/hub/api/rest/oauth2/auth?response_type=token&state=9b8fdea0-fc3a-410c-9577-5dee1ae028da&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized&request_credentials=skip&client_id=98071167-004c-4ddf-ba37-5d4599fdf319&scope=0-0-0-0-0%2098071167-004c-4ddf-ba37-5d4599fdf319
To obtain an access token from YouTrack, you need to provide values for the following parameters in your authorization requests:
Parameter | Description |
---|---|
response_type | Specifies the grant type in an OAuth 2.0 request. For implicit grant, use |
state | An identifier for the current application state. For example, it can be a key for a local storage object that contains information about the location of the current user in the client application. |
redirect_uri | A URI in your client application that can handle responses from Hub. |
request_credentials | A parameter that determines whether the user should be asked to log in. The following values are valid:
|
client_id | The ID of the YouTrack service as registered in the built-in Hub service. To get the YouTrack service ID, open the page: |
scope | The access scope in which your API requests are processed. Use the symbolic name of the YouTrack service in the built-in Hub: |
Responses
The client service should be able to handle responses from Hub at the URL that is passed as the redirect_uri
. Response parameters are passed after a hash sign in the URL. As a result, these parameters are not sent to the server and cannot be intercepted by a malefactor.
If the resource owner grants the access request, Hub issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirect URI using the "application/x-www-form-urlencoded"
format:
Parameter | Description |
---|---|
access_token | The access token issued by Hub. |
token_type | The type of the token that was issued by Hub. The value is case insensitive. |
expires_in | The lifetime of the access token, in seconds. For example, |
scope | Optional if identical to the scope requested by the client; otherwise, required. The scope of the access token in Hub is the |
state | Required if the |
Note that the authorization server (Hub) does not issue a refresh token.
For example, the Hub server redirects the user-agent by sending the following HTTP response:
HTTP/1.1 302 Found
Location:
http://myservice.company.com/authorized#access_token=1443459450185.0-0-0-0-0.98071167-004c-4ddf-ba37-5d4599fdf319.0-0-0-0-0%3B1.MCwCFC%2FYWvLjHdzOdpLleDLITJn4Mz9rAhRklCoZ2dlMkh2aCd1K5QQ89ibsxg%3D%3D&token_type=Bearer&expires_in=3600&scope=0-0-0-0-0%2098071167-004c-4ddf-ba37-5d4599fdf319&state=9b8fdea0-fc3a-410c-9577-5dee1ae028da
OAuth 2.0 Errors
If the request fails due to a missing, invalid, or mismatching redirect URI, or if the client identifier is missing or invalid, the Hub server informs the resource owner of the error and does not automatically redirect the user-agent to the invalid redirection URI.
If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the authorization server informs the client by adding the following parameters to the fragment component of the redirect URI using the "application/x-www-form-urlencoded
" format:
Parameter | Description |
---|---|
error | A single ASCII [USASCII] error code. For a list of possible errors, see Authorization Response Errors and Token Response Errors. |
error_description | Human-readable ASCII [USASCII] text providing additional information, used to help the client developer understand what went wrong. |
error_uri | A URI that identifies a human-readable web page with information about the error, used to provide the client developer with additional information. |
state | Required if a "state" parameter was present in the client authorization request. The exact value received from the client. |
For example, Hub redirects the user-agent by sending the following HTTP response:
HTTP/1.1 302 Found
Location: https://myservice.company.com/cb#error=access_denied&state=xyz
Authorization Response Errors
The following errors can be returned by a request to the authorization endpoint.
Token Response Errors
The following errors can be returned by a request to the token endpoint. For more information, read the definition of each error as defined in the RFC6749 standard.
Error | Description | Solution |
---|---|---|
The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. | Check the response header, then check if the request is correct. | |
Client authentication failed. For example, the client is unknown, no client authentication included, or the authentication method is unsupported. | Check the value for the | |
The authorization grant type is not supported by Hub. | Verify that you have set the value for the | |
The scope to which you are requiring access token does not match any registered service. | Verify that you are using the correct value for the |