---
schema: rendered-html/v1
title: "Extension Grants | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/extension-grants.html
generated_at: 2026-06-11T15:02:44.125630+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](jetbrains__com__help__youtrack__devportal__log-in-to-hub-rest-api.md)
- Permanent Token Authorization in Hub
- OAuth 2.0 Authorization in Hub
- Implicit
- Authorization Code
- Refresh Token
- Resource Owner Password Credentials
- Client Credentials
- [Extension Grants](extension-grants.html)
- 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](jetbrains__com__help__youtrack__devportal__log-in-to-hub-rest-api.md)
4. OAuth 2.0 Authorization in Hub
5. [Extension Grants](#0)

# Extension Grants﻿

Last modified: 07 May 2026

An extension grant lets you exchange access tokens from a third-party authorization service with access tokens from Hub. Extension grants are supported by the following authentication module types in Hub:

- JetBrains Account
- OAuth 2.0
- Okta

> ### note
>
> Availability
>
> This functionality is only available in Hub versions 2020.1.12629 and later.

## Reference to the Standard﻿

[Specification for Extension Grants (RFC 6749)](https://tools.ietf.org/html/rfc6749#section-4.5)

## Prerequisites﻿

- The service that you want to retrieve a Hub access token for is registered in Hub.
- An auth module for the third-party authorization service has been created and enabled in Hub.
- A value is stored in the Extension grant setting for the authentication module.

## Exchanging an Access Token﻿

The client exchanges an access token by posting a request to the token endpoint and adding the following parameters using the `"application/x-www-form-urlencoded"` format with UTF-8 character encoding in the entity-body of the HTTP request:

grant\_type
:   Required. Use the value that is stored in the Extension grant setting for the third-party authentication module in Hub.

scope
:   Optional. The scope of the access request. This consists of a space-separated list of IDs for services registered as resource servers in Hub. For example, if the client wants to access issues in YouTrack, it should find out the ID of the YouTrack service in Hub. The client can access more than one resource server with a single access token.

token
:   Required. The token that grants access to the third-party authorization service that is registered in the authentication module.

For example, the client makes the following HTTP request using transport-layer security (with extra line breaks for display purposes only):

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

grant_type=token_exchange&scope=b4f60b9d-4131-4a6c-9367-3c397d380101&token=tGzv3JOkF0XG5Qx2TlKWIA
```

The authorization server (Hub) will:

1. Require client authentication for confidential clients or for any client that was issued client credentials (or with other authentication requirements).
2. Authenticate the client if client authentication is included and ensure that the access token was issued to the authenticated client.
3. Validate the access token.

If the access token is valid and authorized, Hub issues an access token in exchange. The client can then use the Hub token to make subsequent calls to the API.

If the request failed verification or is invalid, Hub returns [an error response.](/help/youtrack/devportal/extension-grants.html#token-exchange-request-error)

## Error Response from Hub for the Token Exchange Request﻿

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

    - `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.
    - `invalid_client` - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the Hub server will respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.
    - `invalid_grant` - The provided authorization grant (e.g., authorization code, resource owner credentials) or token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
    - `unauthorized_client` - The authenticated client is not authorized to use this authorization grant type.
    - `unsupported_grant_type` - The authorization grant type is not supported by Hub.
    - `invalid_scope` - The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

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.

The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.

For example:

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

{
"error":"invalid_request"
}
```

- [Extension Grants](/help/youtrack/devportal/extension-grants.html)
- [Reference to the Standard](/help/youtrack/devportal/extension-grants.html#reference-to-standard-extension-grant)
- [Prerequisites](/help/youtrack/devportal/extension-grants.html#prerequisites)
- [Exchanging an Access Token](/help/youtrack/devportal/extension-grants.html#exchange-access-token)
- [Error Response from Hub for the Token Exchange Request](/help/youtrack/devportal/extension-grants.html#token-exchange-request-error)

Client CredentialsOAuth 2.0 Errors

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

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