REST API — setup and usage

Use the Attachment Manager REST API to list labels, read and change the labels on individual Jira attachments, and find attachments across projects.

Quick start

1. Ask a site or organization admin to enable App REST APIs for Attachment Manager in Atlassian Administration → Apps → Sites → your site → Connected apps → View app details → Details. Copy the base URL shown there.

2. Create an OAuth 2.0 integration in the Atlassian Developer Console. Add Attachment Manager and the required scopes under Permissions, plus read:forge-app:jira.

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

4. Call GET /v1/labels with Authorization: Bearer <access token>.

# Set BASE to the URL copied from Connected apps (no trailing slash).
export BASE="https://YOUR-SITE.atlassian.net/gateway/api/svc/jira/apps/APP-ID_ENVIRONMENT-ID"
# Supply ACCESS_TOKEN from your integration’s secure token store.
curl --request GET --url "$BASE/v1/labels" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Accept: application/json"

Authentication and authorization

Choose the correct base URL

All paths below are relative to BASE. Both forms below reach the same app installation. Prefer copying the complete base 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}

Enable the API for the site

A site or organization admin enables App REST APIs under Attachment Manager’s Connected apps details. App REST APIs are disabled by default. Disabling the setting immediately blocks external API calls for that site; it does not disable the app’s Jira interface.

Configure an OAuth 2.0 integration

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

2. Under Permissions, choose Add Marketplace or custom app; select the site, Attachment Manager, and the correct environment. Add the app scopes required for the operations below.

3. Also add the Jira product scope read:forge-app:jira.

4. Under Authorization, configure your callback URL. Start from the authorization URL generated by the console. Keep its sns parameter, which associates custom scopes with Attachment Manager.

5. For unattended renewal, include offline_access in the scope parameter (space-separated; URL-encode spaces as %20). Complete consent, then exchange the code returned to the callback.

Atlassian: access REST APIs exposed by a Forge app

Atlassian Developer Console

Exchange the code for tokens

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 includes access_token, token_type, expires_in and scope. When offline_access was granted, it also includes refresh_token. Access tokens last one hour; use expires_in to schedule renewal. Keep client secrets and tokens in your integration’s secure storage.

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 the access token across requests; do not request a new token for every API call.

Next steps

• REST API reference

• REST API errors and limits

Last updated: September 20, 2026