REST API — setup and usage

Use the Support Time Contract Management REST API to create, import, read, update and delete support contracts, and read their calculated logged hours, remaining hours and status. It works on Jira Cloud and Jira Service Management Cloud sites where the app is installed.

This page is for developers. Administrators enable the API for their site and share the complete base URL with the integration owner.

Quick start

1. Check that the app license is active and that Advanced is selected, or that the API rollout is enabled for your Standard site.

2. Ask a site or organization admin to enable App REST APIs in Atlassian Administration → Apps → Sites → your site → Connected apps → Support Time Contract Management → View app details → Details. Copy the complete base URL shown there.

3. Create an OAuth 2.0 integration in the Atlassian Developer Console. Add the app scopes you need and the Jira scope read:forge-app:jira.

4. Set a callback URL, obtain consent using the console-generated authorization URL, and exchange the returned code for an access token.

5. Call GET /v1/contracts with Authorization: Bearer <access token>.

# Copy the complete base URL from Connected apps; omit the trailing slash.
export BASE="https://YOUR-SITE.atlassian.net/gateway/api/svc/jira/apps/9e9acd44-46e1-48d1-8466-a07544d57455_ENVIRONMENT-ID"
# Supply ACCESS_TOKEN from your integration’s secure token store.
curl --request GET --url "$BASE/v1/contracts" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Accept: application/json"

Authentication and authorization

Choose the base URL

All endpoint paths are relative to BASE. These two URL forms reach the same app installation. Prefer copying the complete URL from Connected apps after enabling the API.

https://api.atlassian.com/svc/jira/{cloudId}/apps/{appId}_{environmentId}
https://{your-site}.atlassian.net/gateway/api/svc/jira/apps/{appId}_{environmentId}

1. Enable the API for the site

1. Open Atlassian Administration and select your organization.

2. Go to Apps → Sites and select the site where Support Time Contract Management is installed.

3. Select Connected apps, find Support Time Contract Management, then choose View app details.

4. On the Details tab, find App REST APIs, choose Enable app REST APIs and confirm. Share the displayed base URL with your developer.

App REST APIs are off by default. Disabling the setting immediately blocks API calls from every integration on that site; the app’s Jira interface continues to work.

Open Atlassian Administration

2. Configure an OAuth 2.0 integration

1. In the Atlassian Developer Console, choose Create → OAuth 2.0 integration and name it. The person connecting the integration must be a member of the target site.

2. Open Permissions → Add Marketplace or custom app. Select your site, Support Time Contract Management and its released environment. Select only the app scopes required by your integration, then choose Add.

3. Under Permissions, also add the Jira product scope read:forge-app:jira.

4. Under Authorization, set your callback URL. Start with the authorization URL generated by the console for the app. Preserve its sns parameter, which associates the custom scopes with this app.

5. For unattended token renewal, include offline_access in the scope parameter. Scopes are separated by spaces; URL-encode spaces as %20. Obtain consent for the selected site.

Open Atlassian Developer Console

Scopes and operations

Write access does not include read access. An integration that imports contracts and polls their progress needs both write:contract:custom and read:contract:custom, plus read:forge-app:jira.

3. Exchange the authorization code for tokens

Open the console-generated authorization URL, choose the site and accept. Atlassian redirects to your callback with a code parameter. Exchange the code promptly; it is valid for only a few minutes.

curl --request POST --url https://auth.atlassian.com/oauth/token \
  --header "Content-Type: application/json" \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "CODE_FROM_CALLBACK",
    "redirect_uri": "YOUR_CALLBACK_URL"
  }'

The response contains access_token, token_type, expires_in and scope. If offline_access was granted, it also contains refresh_token. Access tokens last one hour; use expires_in to schedule renewal. Store tokens and client secrets securely.

Renew access

curl --request POST --url https://auth.atlassian.com/oauth/token \
  --header "Content-Type: application/json" \
  --data '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_LATEST_REFRESH_TOKEN"
  }'

Refresh tokens rotate: store the new refresh token returned by each renewal. A refresh token expires after 90 days without use. Reuse an access token across calls.

4. Send the token on every request

GET /v1/contracts HTTP/1.1
Authorization: Bearer {access_token}
Accept: application/json

POST and PUT requests also require Content-Type: application/json.

Who the API acts as

Calls are attributed to the Atlassian account that gave consent; that account is recorded on contract changes. For unattended integrations, use a dedicated Atlassian account.

Contracts are app-managed data. Logged hours are computed as the app across the JSM projects configured in its settings. The caller’s individual project permissions do not change which worklogs are summed.

Atlassian: access REST APIs exposed by a Forge app

Related documentation

• REST API reference

• REST API errors and limits

• Upgrading to the Advanced Edition

Last updated: October 08, 2026