---
schema: rendered-html/v1
title: "Authorization Code | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/Authorization-Code.html
generated_at: 2026-06-11T14:41:01.773811+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API
- Hub REST API Guide
- Log in to Hub
- Permanent Token Authorization in Hub
- OAuth 2.0 Authorization in Hub
- [Implicit](jetbrains__com__help__youtrack__devportal__implicit.md)
- [Authorization Code](Authorization-Code.html)
- Refresh Token
- Resource Owner Password Credentials
- [Client Credentials](jetbrains__com__help__youtrack__devportal__client-credentials.md)
- Extension Grants
- OAuth 2.0 Errors
- REST API URL and Endpoints
- Hub OpenAPI Specification (OAS)
- Hub API Field Syntax
- Sort Syntax in Hub
- Hub API Query Syntax
- Hub REST API Reference

1. Hub REST API
2. Hub REST API Guide
3. Log in to Hub
4. OAuth 2.0 Authorization in Hub
5. [Authorization Code](#0)

# Authorization Code﻿

Last modified: 07 May 2026
> ### tip
>
> Since Hub 2021.1, the Authorization code flow supports PKCE extension.
>
> The proof key for code exchange (PKCE) is an additional protection code that further enhances the Hub authorization flow. It was created to offer desktop and mobile client applications a more secure and robust sign-in experience and is recommended by IETF (The Internet Engineering Task Force) among other OAuth 2.0 best practices.

## Reference to the Standard﻿

See [Authorization code flow specification](https://tools.ietf.org/html/rfc6749#section-4.1) for more info.

See [Proof Key for Code Exchange by OAuth Public Clients](https://tools.ietf.org/html/rfc7636) for more info.

## Prerequisites﻿

**Client**.

The authorization code grant type is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (using redirection) from the authorization server.

Client service\_ID
:   An ID of the service associated with the client in Hub.

Client service\_secret
:   The secret of the service associated with the client in Hub.

scope
:   A space separated list of IDs of the registered in Hub services associated with the resource servers. 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.

redirect\_URI of the client
:   An URI at the client application that can handle response from authorization server.

code\_verifier
:   A high-entropy cryptographic random string that uses the unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"`, with a minimum length of 43 characters and a maximum length of 128 characters.

    The client creates a code verifier for *each* OAuth 2.0 Authorization Request.

    It is recommended that the output of a suitable random number generator be used to create a 32-octet sequence. The octet sequence is then base64url-encoded to produce a 43-octet URL safe string to use as the code verifier. For details, see [Section 4.1 of RFS7636](https://tools.ietf.org/html/rfc7636#section-4.1).

code\_challenge
:   A code challenge is derived by client from the *code verifier* using either `plain` or `S256` transformations:

    - `plain`:

      ```
      code_challenge = code_verifier
      ```
    - `S256`:

      ```
      code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
      ```

    For details, see [Section 4.2 of RFS7636](https://tools.ietf.org/html/rfc7636#section-4.2).

code\_challenge\_method
:   This parameter defines the type of transformation used to create the `code_challenge`: either `plain` or `S256`.

    > ### note
    >
    > If the client is capable of using `S256`, it **must** use `S256`. Clients are permitted to use `plain` transformation only if they cannot support `S256` for some technical reason.

    For details, see [Section 4.2 of RFS7636](https://tools.ietf.org/html/rfc7636#section-4.2).

Hub URL
:   An URL of Hub server.

State
:   An identifier of current application state. For example, it can be a key for a local storage object that contains information about current user location in the client service.

request\_credentials
:   A parameter that controls if login form should be shown to a user. Following values are valid:

    - `skip` — use this option, if the client service generally allows anonymous access. It works as following:

      - if the user is already logged in to Hub, then authorize her to the client service,
      - if the user is not logged in to Hub and guest account is not banned, then authorize guest to the client service,
      - if the user is not logged in to Hub and guest account is banned then navigate to login form.
    - `silent` — same as `skip`, but will return back anyway. If guest account is banned, then this option returns to the client service with an authentication error.
    - `required` — logs out user and shows login form. Use this option as a response to log out in the client service.
    - `default` — use this option if the client service does not allow anonymous access. It works as following:

      - if the user is already logged in to Hub, then authorize her to the client service,
      - if the user is not logged in to Hub, then navigate her to login form.

access\_type
:   Indicates whether the application requires access to Hub when the user is not online. Allowed values: `online` (used by default) and `offline`. If the application requires refreshing access tokens when the user is not online, use the `offline` value. In this case Hub issues a refresh token for the application the first time it exchanges an authorization code for a user. Refer to the Refresh Token page for more information.

## Sending User to the Authorization Server (Hub)﻿

To start authentication code should send to browser redirect response to the URL in the following format:

```
${Hub Service URL}/api/rest/oauth2/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client service ID}&scope=${Scope}&access_type={online|offline}&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}
```

.

In this request:

- `code_challenge` - required, when using PKCE extension
- `code_challenge_method` - optional, defaults to "plain" if not present in the request.

Example:

```
https://hub.company.com/api/rest/oauth2/auth?response_type=code&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&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256
```

To instruct Hub to issue the refresh token, add the `access_type=offline` parameter to your request:

```
${Hub Service URL}/api/rest/oauth2/auth?response_type=code&state=${State}&redirect_uri=${Client redirect URI}&request_credentials=${Request credentials mode}&client_id=${Client service ID}&scope=${Scope}&access_type=offline&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}
```

.

## Handling Redirect Back from the Authorization Server (Hub)﻿

If the resource owner grants the access request, the Hub issues an authorization code and delivers it to the client by adding the following parameters to the query component of the redirection URI using the `"application/x-www-form-urlencoded"` format:

code
:   The authorization code generated by the authorization server. The authorization code will expire shortly after it is issued to mitigate the risk of leaks. The client must not use the authorization code more than once. If an authorization code is used more than once, Hub will deny the request. The authorization code is bound to the client identifier and redirection URI.

state
:   The exact value received from the client in the authorization request.

For example, the authorization server (Hub) redirects the user-agent by sending the following HTTP response:

```
HTTP/1.1 302 Found
Location: https://myservice.company.com/authorized?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
```

The client must ignore unrecognized response parameters.

## Handling Error Redirect Back from Hub﻿

If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, Hub informs the client by adding the following parameters to the query component of the redirection URI using the "`application/x-www-form-urlencoded`" format:

error
:   A single ASCII [USASCII] error code from the following:

    - `invalid_request` - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
    - `unauthorized_client` - The client is not authorized to request an authorization code using this method.
    - `access_denied` - The resource owner or Hub denied the request.
    - `unsupported_response_type` Hub does not support obtaining an authorization code using this method.
    - `invalid_scope` The requested scope is invalid, unknown, or malformed.
    - `server_error` The Hub server 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 via an HTTP redirect.)
    - `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 via an HTTP redirect.)

error\_description
:   Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred.

error\_uri
:   A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.

state
:   Required if a "state" parameter was present in the client authorization request. The exact value received from the client.

## Exchanging Code for an Access Token﻿

After the client receives the code it can exchange it for an access token.

The client makes a request to the Hub token endpoint by sending the following parameters using the "`application/x-www-form-urlencoded`" format with a character encoding of UTF-8 in the HTTP request entity-body:

```
POST /api/rest/oauth2/token
Host: ${Hub Service URL}
Accept: application/json
Authorization: Basic ${base64(${Client service ID} + ":" + ${Client service secret})}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=${Code received on a previous step}&redirect_uri=${Client redirect URI}&code_verifier={code_verifier}
```

In this request:

- `code_verifier` - required, when using PKCE extension.
- `client_id` - required, when using PKCE extension for Public Clients (untrusted services) and when `Auth Header` is omitted.

> ### note
>
> When using PKCE extension:
>
> - For confidential clients (trusted services) `Auth Header` is required.
> - For public clients (untrusted services) `Auth Header` can be omitted but, in this case, `client_id` parameter becomes required.

Example:

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

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fmyservice.company.com%2Fauthorized&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

## Handling Access Token Response﻿

If the access token request is valid and authorized, Hub issues an access token. If the request client authentication failed or is invalid, the Hub server returns an error response.

Example of a successful response:

```
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
"access_token":"1443459450185.0-0-0-0-0.98071167-004c-4ddf-ba37-5d4599fdf319.0-0-0-0-0%3B1.MCwCFC%2FYWvLjHdzOdpLleDLITJn4Mz9rAhRklCoZ2dlMkh2aCd1K5QQ89ibsxg%3D%3D
"expires_in":3600,
}
```

- [Authorization Code](/help/youtrack/devportal/Authorization-Code.html)
- [Reference to the Standard](/help/youtrack/devportal/Authorization-Code.html#StandardReference)
- [Prerequisites](/help/youtrack/devportal/Authorization-Code.html#prerequisites)
- [Sending User to the Authorization Server (Hub)](/help/youtrack/devportal/Authorization-Code.html#SendUserToHub)
- [Handling Redirect Back from the Authorization Server (Hub)](/help/youtrack/devportal/Authorization-Code.html#HandleRedirectFromHub)
- [Handling Error Redirect Back from Hub](/help/youtrack/devportal/Authorization-Code.html#ErrorRedirectFromHub)
- [Exchanging Code for an Access Token](/help/youtrack/devportal/Authorization-Code.html#ExchangingCodeForToken)
- [Handling Access Token Response](/help/youtrack/devportal/Authorization-Code.html#HandlingTokenResponse)

[Implicit](jetbrains__com__help__youtrack__devportal__implicit.md)Refresh Token

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
