OAuth 2.0 Authorization

To access YouTrack resources via REST API you must log in, authorize, and obtain an access token for YouTrack. Authorization is provided by Hub service.

If you use an external Hub service for your standalone YouTrack, then you can use all OAuth 2.0 authorization flows supported by Hub. For detailed description, refer to the Hub Online Documentation.

The built-in Hub service that comes bundled with YouTrack supports Implicit OAuth 2.0 authorization flow, only.

Hub implementation of OAuth 2.0 supports several authentication/authorization flow. To access resources of Hub itself and services connected to Hub, a client should obtain an access token. The flow that the client may use depends on:

What information the client has (service credentials / user credentials).
Where from the client access resources (from a browser / from the server side / from a standalone application).

What Information You Should Have
OAuth 2.0 Endpoints for Built-in Hub
Register Client as a Service
- Sample script for registering client as a service
  - Request
  - Response

What Information You Should Have

Parameter	Is it required?	Description
`Client service ID`	Always	An identifier (ID) of the service associated with the client in Hub.
`Client service secret`	Depends on flow	A secret for the service associated with the client in Hub.
`Scope`	Always	An ID of the registered in Hub service associated with the resource server. For example, if the client wants to access issues in YouTrack, it should find out the id of YouTrack service in Hub. The client can access more then one resource server with a single access token. In this case, the Scope is the space-separated list of the IDs of the services registered in Hub.
`Client redirect URI`	Depends on flow	An URI at the client application that can handle response from authorization server (Hub).
`Username`	Depends on flow	End-user's username, or id, or email.
`Password`	Depends on flow	End-user's password.

OAuth 2.0 Endpoints for Built-in Hub

For the built-in Hub service, the OAuth 2.0 endpoints for authentication and token are:

Authentication endpoint URL: <Hub Service BaseURL>/api/rest/oauth2/auth
Token endpoint URL: <Hub Service URL>/api/rest/oauth2/token

<Hub Service URL> is the URL that is configured for the Hub service in your network environment. For example, you have your company's server www.mycompany.com and a Hub service. You can configure Hub to be accessible by server.myjetbrains.com/hub or, let's say hub.mycompany.com. Subsequently, the OAuth 2.0 endpoints are as follows, respectively:

For www.mycompany.com/hub: https://www.mycompany.com/hub/api/rest/oauth2/auth and https://www.mycompany.com/hub/api/rest/oauth2/token
For hub.mycompany.com: https://hub.mycompany.com/api/rest/oauth2/auth and https://hub.mycompany.com/api/rest/oauth2/token.

Register Client as a Service

To enable authorization you should register your client as a Hub service. You can do it either in administrative UI or programmatically. Basically, you just send POST request on /services URL and get credentials of the newly created service in response.

Sample script for registering client as a service

The following sample script considers Hub service to be installed to https://hub.company.com and a client OAuth 2.0 service - to https://myservice.company.com.

Request

POST /api/rest/services?fields=id,secret HTTP/1.1
Host: hub.company.com
Accept: application/json
Content-Type: application/json

{
"name": "My Service",
"homeUrl": "https://myservice.company.com",
"redirectUris": ["https://myservice.company.com/authorized"],
"applicationName": "My Service",
"vendor": "Company Inc.",
"version": "1.0"
}

Response

{
"id": "98071167-004c-4ddf-ba37-5d4599fdf319",
"secret": "eAUyKgVfhSbV"
}

You can later use service's id and secret for authorization.

Service in Hub can be either trusted or not. If a service is trusted, then it can access Hub resource servers on behalf of itself. Also, when a user is sent from the trusted service to authorize himself, the user sees no additional warning.

Last modified: 2 February 2017