# OAuth 2.0 Authorization

OAuth 2.0 lets an application obtain an access token and access YouTrack resources on behalf of an authorizing user. The Hub service connected to YouTrack provides OAuth authorization.

## Choose an Authorization Method

Use OAuth 2.0 when your application needs users to authorize access to YouTrack. For scripts and integrations that don't require interactive user authorization, use a [permanent token](authentication-with-permanent-token.html).

* For new applications, use the [Authorization Code flow](Authorization-Code.html) with PKCE when possible.

* Use [implicit authorization](#implicit-authorization-grants) only for browser-based clients that can't use the Authorization Code flow.

## Availability

OAuth 2.0 authorization is provided by the Hub service connected to YouTrack. Starting with YouTrack 2026.2, system administrators can create and manage OAuth clients directly in YouTrack.

| YouTrack deployment | OAuth support |
| --- | --- |
| YouTrack Cloud or YouTrack Server with a built-in Hub service | OAuth clients are managed in YouTrack. Each client can be configured with the supported authorization flows, redirect URIs, and access to YouTrack resources on behalf of users. |
| YouTrack Server connected to an external Hub service | Available OAuth 2.0 authorization flows are determined by the external Hub service. Availability depends on the Hub version and configuration. For details, see the [Hub documentation](https://www.jetbrains.com.cn/en-us/help/hub/OAuth-2.0-Authorization.html). |

## Endpoints

The built-in Hub service uses the following OAuth 2.0 endpoints:

| Endpoint | URL |
| --- | --- |
| Authorization | `<Hub service URL>/api/rest/oauth2/auth` |
| Token | `<Hub service URL>/api/rest/oauth2/token` |

* For a YouTrack Server installation, append `/hub` to the YouTrack Base URL. For example, `https://www.company-youtrack.com/hub`. You can find the Base URL on the Global Settings page.

* For a YouTrack Cloud instance, replace the `/youtrack` path in the YouTrack Base URL with `/hub`. For example, `https://company-domain.youtrack.cloud/hub`. You can find the Base URL on the Domain Settings page.

## OAuth Clients

An OAuth client registration identifies an application to the Hub service and defines how the application can request access to YouTrack. REST API integrations, MCP clients, and other applications that support OAuth can use these registrations.

Each registered application has a client ID. Confidential clients also use a client secret. For new integrations, public clients should use the [Authorization Code flow](Authorization-Code.html) with PKCE without a client secret.

Access tokens issued for an OAuth client act on behalf of the user who authorized the application. They don't grant access beyond the permissions of the authorizing user.

A system administrator manages preregistered OAuth clients and automatic client registration in YouTrack. For configuration instructions, see [OAuth Clients in YouTrack Cloud](https://www.jetbrains.com.cn/en-us/help/youtrack/cloud/oauth-clients.html) or [OAuth Clients in YouTrack Server](https://www.jetbrains.com.cn/en-us/help/youtrack/server/oauth-clients.html).

### Preregistered Clients for MCP

For preregistration, a system administrator creates an OAuth client using the redirect URI and OAuth requirements provided by the MCP client application. The administrator then provides the generated client ID and, for a confidential client, the client secret to the application.

After the OAuth client is configured, users can approve the application's access request in YouTrack. This lets the application access YouTrack on behalf of the user without storing a permanent token locally.

### Automatic OAuth Client Registration for MCP

Starting with YouTrack 2026.2, Client ID Metadata Documents (CIMD) let compatible MCP clients register OAuth clients automatically during authorization. Automatic registration must first be enabled by a system administrator and is disabled by default.

When automatic registration is enabled, users can connect a CIMD-compatible client using only the YouTrack MCP endpoint URL, for example `https://youtrack.example.com/mcp`, and approve its access request in YouTrack.

CIMD is different from Dynamic Client Registration. YouTrack doesn't support OAuth Dynamic Client Registration for MCP clients. If an MCP client doesn't support CIMD, use either a preregistered OAuth client or token-based authorization.

## Implicit Authorization

YouTrack supports OAuth 2.0 authorization with implicit authorization as specified in the [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749#section-4.2).

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:

```HTML
${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:

```HTML
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 `token`. |
| `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 recognized:                                * `skip` — use when the client application allows anonymous access. * If the user is already logged in to Hub, the user is granted access to the client application. * If the user is not logged in to Hub and the guest account is not banned, the user is granted access to the client application as a guest. * If the user is not logged in to Hub and the guest account is banned, the user is redirected to the login page.    * `silent` — same as `skip`, but redirects the user to the client application in all cases. If the guest account is banned, the user is redirected to the client application with an authentication error.    * `required` — logs the user out of Hub and redirects them to the login page. Use as a response to a logout request in the client application.    * `default` — use when the client application does not allow anonymous access. * If the user is already logged in to Hub, the user is granted access to the client application. * If the user is not logged in to Hub, the user is redirected to the login page.    |
| `client_id` | The ID of the YouTrack service as registered in the built-in Hub service. To get the YouTrack service ID, open the `Hub Integration` page.     ![The YouTrack service ID stored in a built-in Hub service.](https://resources.jetbrains.com.cn/help/img/youtrack/oauthYTServiceId.png)   This page is accessible from the `Administration > Server Settings > Global Settings` page. For more information about this integration, please refer to the [YouTrack documentation](https://www.jetbrains.com.cn/en-us/help/youtrack/cloud/hub-integration.html).    |
| `scope` | The access scope in which your API requests are processed. Use the symbolic name of the YouTrack service in the built-in Hub: `YouTrack`. |

### 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, `3600` denotes that the access token expires one hour from the time the response was generated. |
| `scope` | Optional if identical to the scope requested by the client; otherwise, required. The scope of the access token in Hub is the `service_id`. |
| `state` | Required if the `state` parameter was specified in the client authorization request. The exact value received from the client. |

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:

```HTML
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](#AuthorizationResponseErrors) and [Token Response Errors](#token-response-error-codes). |
| `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:

```HTML
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.

| Error | Description | Solution |
| --- | --- | --- |
| `invalid_request` | The authorization request to Hub is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. | Verify that all of the parameters are correct, that the provided `service_id` exists, and so on. |
| `unauthorized_client` | Either the client is not authorized to request an authorization code using this method or `redirect_URI` of the service either is incorrect or missing. |   1. Make sure the `redirect_uri` is correct and properly registered as one of the service's redirect URIs.    2. Make sure your service provides at least one `redirect_uri` in Hub.   |
| `access_denied` | The resource owner or Hub denied the request. | Verify that you are using the correct value for the `scope` parameter. |
| `unsupported_response_type` | Hub does not support obtaining an authorization code using this method. | Verify that you have set the value for the `response_type` to `token`. |
| `invalid_scope` | The scope for which authorization is requested, does not match any registered service. | Make sure that request is correct. |
| `server_error` | The Hub service encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client with an HTTP redirect.) | The connection between YouTrack and the Hub service may be out of sync. Open the Hub Integration page in YouTrack and run diagnostics. |
| `temporarily_unavailable` | The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client with an HTTP redirect.) | The connection between YouTrack and the Hub service may be out of sync. Open the Hub Integration page in YouTrack and run diagnostics. |

#### 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](https://tools.ietf.org/html/rfc6749#section-5.2).

| Error | Description | Solution |
| --- | --- | --- |
|   `invalid_request`  |    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. |
|   `invalid_client`  | Client authentication failed. For example, the client is unknown, no client authentication included, or the authentication method is unsupported.  | Check the value for the `client_id` parameter. |
|   `unsupported_grant_type`  | The authorization grant type is not supported by Hub. | Verify that you have set the value for the `response_type` to `token`. |
|   `invalid_scope`  | 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 `scope` parameter. |