EAP documentation: Jira OAuth 2.0 provider API
Jira (Data Center and Server) provides APIs to allow external services to access resources on a user’s behalf with the OAuth 2.0 protocol.
Supported OAuth 2.0 flows
We support the following OAuth 2.0 flows:
Authorization code with Proof Key for Code Exchange (PKCE)
Authorization code
We don’t support Implicit Grant and Resource Owner Password Credentials flows, as they will be deprecated in the next OAuth specification version.
For more information on how these flows work, see OAuth RFC. This should help you understand the flows and choose the right one for you.
Security recommendations
Here are some recommendations on how to improve security:
Preventing CSRF attacks
To protect redirect-based flows, the OAuth specification recommends the use of “One-time use CSRF tokens carried in the state parameter, which are securely bound to the user agent” using the state
query parameter, with each request to the /rest/oauth2/latest/authorize
endpoint. This can prevent CSRF attacks.
Using HTTPS in production
For production environments, use HTTPS for the redirect_uri
. This is important, as OAuth 2.0 bases its security on the transport layer. For more info, see the OAuth 2.0 RFC and the OAuth 2.0 Threat Model RFC.
For the same reason, we also enforce HTTPS for the base URL of production environments.
Authorization code with Proof Key for Code Exchange (PKCE)
This flow lets you securely perform the OAuth exchange of client credentials for access tokens on public clients.
Parameters
Here are parameters you’ll use in this flow:
Parameter | Description | Required |
---|---|---|
| URL the user is redirected to after authorizing the request. | Yes |
| Client ID received from Jira after registering your application. | Yes |
| Authorization code. | Yes |
| Scopes that define application’s permissions to the user account. For more info, see Scopes. | Yes |
|
| Yes |
| Can be | Yes |
| High-entropy cryptographic random STRING using the unreserved characters: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~". It must be between 43-127 characters. For more info, see the RFC. | Yes |
| A value that can't be predicted. It will be used by the client to maintain state between the request and callback. It should also be used as a CSRF token. It can be generated in a similar manner to | No |
Before you begin
Register your application in Jira by creating an incoming link in application links. During registration, you can enable proper scopes to limit the range of resources which the application can access. After creating the link, you should receive the OAuth credentials: Client ID and Client secret - keep them secure.
Before starting the flow, generate the
state
(optional),code_verifier
,code_challenge
, andcode_challenge_method
.
Steps
1. Request the authorization code by redirecting the user to the /rest/oauth2/latest/authorize
page with the following query parameters:
curl https://atlassian.example.com/rest/oauth2/latest/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=SCOPE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
This is the consent screen that asks the user to approve the application’s request to access their account with the scopes specified in scope
. The user is then redirected to the URL specified in redirect_uri
. The redirect includes the authorization code, like in the following example:
https://atlassian.example.com/plugins/servlet/oauth2/consent?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE&code_challenge_method=CODE_CHALLENGE_METHOD&code_challenge=CODE_CHALLENGE
2. With the authorization code
returned from the previous request, you can request an access_token
, with any HTTP client. The following example uses curl:
curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER
Example response
{
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
"created_at": 1607635748
}
3. To retrieve a new access_token
, use the refresh_token
parameter. Refresh tokens may be used even after the access_token
itself expires. The following request:
Invalidates the existing
access_token
andrefresh_token
.Sends new tokens in the response
curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI
Example response
{
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImJmZjg4MzU5YTVkNGUyZmQ3ZmYwOTEwOGIxNjg4MDA0In0.BocpI91mpUzWskyjxHp57hnyl8ZcHehGJwmaBsGJEMg",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Ijg1NjQ1YjA1NGJiYmZkNjVmMDNkMzliYzM0YzQ4MzZjIn0.4MSMIG46zjB9QCV-qCCglgojM5dL7_E2kcqmiV46YQ4",
"created_at": 1628711391
}
You can now make requests to the API with the access token. For more info, see Access Jira API with access token below.
Authorization code
This flow lets you securely perform the OAuth exchange of client credentials for access tokens on public clients.
Parameters
Here are parameters you’ll use in this flow:
Parameter | Description | Required |
---|---|---|
| URL the user is redirected to after authorizing the request. | Yes |
| Client ID received from Jira after registering your application. | Yes |
| Authorization code. | Yes |
| Scopes that define application’s permissions to the user account. For more info, see Scopes. | Yes |
| A value that can't be predicted. It will be used by the client to maintain state between the request and callback. It should also be used as a CSRF token. | No |
Before you begin
Register your application in Jira by creating an incoming link in application links. During registration, you can enable proper scopes to limit the range of resources which the application can access. After creating the link, you should receive the OAuth credentials: Client ID and Client secret - keep them secure.
If you want to use the optional
state
parameter, generate it before starting the flow.
Steps
1. Request the authorization code by redirecting the user to the /oauth/authorize
page with the following query parameters:
curl https://atlassian.example.com/rest/oauth2/latest/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE&scope=SCOPE
This is the consent screen that asks the user to approve the application’s request to access their account with the scopes specified in scope
. The user is then redirected to the URL specified in redirect_uri
. The redirect includes the authorization code, like in the following example:
https://atlassian.example.com/plugins/servlet/oauth2/consent?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE
2. With the authorization code (response_type
) returned from the previous request, you can request an access_token
, with any HTTP client. The following example uses Ruby’s rest-client:
curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI
Example response
{
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjNmMTQ3NTUzYjg3OTQ2Y2FhMWJhYWJkZWQ0MzgwYTM4In0.EDnpBl0hd1BQzIRP--xEvyW1F6gDuiFranQCvi98b2c",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImMwZTMxYmZjYTI2NWI0YTkwMzBiOGM2OTJjNWIyMTYwIn0.grHOsso3B3kaSxNd0QJfj1H3ayjRUuA75SiEt0usmiM",
"created_at": 1607635748
}
3. To retrieve a new access_token
, use the refresh_token
parameter. Refresh tokens may be used even after the access_token
itself expires. This request:
Invalidates the existing
access_token
andrefresh_token
.Sends new tokens in the response.
curl -X POST https://atlassian.example.com/rest/oauth2/latest/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token&redirect_uri=REDIRECT_URI
Example response
{
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6ImJmZjg4MzU5YTVkNGUyZmQ3ZmYwOTEwOGIxNjg4MDA0In0.BocpI91mpUzWskyjxHp57hnyl8ZcHehGJwmaBsGJEMg",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Ijg1NjQ1YjA1NGJiYmZkNjVmMDNkMzliYzM0YzQ4MzZjIn0.4MSMIG46zjB9QCV-qCCglgojM5dL7_E2kcqmiV46YQ4",
"created_at": 1628711391
}
You can now make requests to the API with the access token returned. For more info, see Access Jira API with access token below.
Access Jira API with access token
The access token allows you to make requests to the API on behalf of a user. You can put the token in the Authorization header:
curl --header "Authorization: Bearer OAUTH2-TOKEN" "https://atlassian.example.com/rest/api/latest/issue/JRA-9"
Scopes
The scope
parameter is required in both flows. It allows you to specify the permission scopes your application can request from the authorizing user. Note that regardless of which scopes you choose, the actual permissions will always be capped at what the user can actually do.
Here you can find the scope keys you can use in your requests, as values of the scope
parameter:
Scope key | Description | Implied scopes |
---|---|---|
READ | View projects and issues View projects and issues the user account can view, including any related items, such as dashboards, filters, attachments, or comments. Also view the user profile. | READ |
WRITE | Create, update, and delete projects and issues Create, update, and delete projects and issues the user account can change, including any related items, such as dashboards, filters, attachments, or comments. Also change the user profile. | READ, WRITE |
ADMIN | Administer Jira Perform most administrative functions on the entire Jira instance, excluding functions such as backups, imports, and infrastructure settings which are limited to system administrators. | READ, WRITE, ADMIN |
SYSTEM_ADMIN | Administer Jira system Perform all administrative functions on the entire Jira instance, including functions such as backups, imports, and infrastructure settings. | READ, WRITE, ADMIN, SYSTEM_ADMIN |