Atlassian JWT

3.0.0 verified Fri May 01 auth: no python

JSON Web Token (JWT) generation with Atlassian query-string-hash claim support. Wraps PyJWT and adds the 'qsh' claim needed for Atlassian Connect add-ons. Current version 3.0.0, release cadence is irregular.

pip install atlassian-jwt

Common errors

error ImportError: cannot import name 'create_jwt' from 'atlassian_jwt' ↓

cause Installed version is too old or package not installed at all.

fix

Upgrade to atlassian-jwt >= 3.0.0: pip install --upgrade atlassian-jwt

error AttributeError: module 'jwt' has no attribute 'create_jwt' ↓

cause Imported the wrong module (PyJWT's jwt instead of atlassian_jwt).

fix

Use 'from atlassian_jwt import create_jwt' instead of 'import jwt'.

error atlassian_jwt.exceptions.InvalidIssuerError: Invalid issuer ↓

cause The issuer string does not match the expected key in the secret store.

fix

Ensure the issuer matches the add-on key registered in Atlassian Connect.

Warnings

gotcha The 'qsh' claim is automatically computed from HTTP method and URI. If you change the method or URI after calling create_jwt, the token becomes invalid. ↓

fix Regenerate the token for each request, or compute qsh manually using compute_qsh and pass it to encode.

breaking Version 3.0.0 dropped support for Python 2 and the old API (e.g., 'create_jwt' now returns a string, not a dictionary). ↓

fix Use the new API: call create_jwt(issuer, secret) or encode(payload, secret). Check the migration guide.

deprecated The function 'encode_jwt' (with parameters as dict) was deprecated in 2.0.0 and removed in 3.0.0. ↓

fix Replace encode_jwt with create_jwt(issuer, secret) or encode(payload, secret).

Imports

atlassian_jwt
wrong
```
from atlassian_jwt import *
```
correct
```
import atlassian_jwt
```
Wildcard imports are discouraged and may lead to namespace pollution
create_jwt
wrong
```
from jwt import create_jwt
```
correct
```
from atlassian_jwt import create_jwt
```
PyJWT's jwt module does not export create_jwt; using atlassian_jwt is required
encode
wrong
```
import jwt; jwt.encode(...)
```
correct
```
from atlassian_jwt import encode
```
atlassian_jwt.encode adds the 'qsh' claim automatically; using raw PyJWT.encode will omit qsh

Quickstart

Encode a JWT with an Atlassian query-string-hash (qsh) claim for a GET request.

from atlassian_jwt import create_jwt
import os

# Typically a shared secret from Atlassian Connect
secret = os.environ.get('ATLASSIAN_SHARED_SECRET', 'test-secret')
issuer = 'plugin-key'

# Create a JWT for a request
jwt_token = create_jwt(issuer, secret, method='GET', uri='/rest/api/2/issue')
print(jwt_token)