Authentication

All requests to the Capacity Planning REST API must be authenticated. The API supports the following authentication methods.

API tokens

Personal API tokens (Basic auth)

Use a personal API token for scripts, automation, and quick integrations. Pass your Atlassian account email and API token using HTTP Basic authentication:

1
2
curl --request GET \
  --url "https://api.atlassian.com/ex/capacity-planning/{cloudId}/v1/contributions?contributorDataId={contributorAri}&workDataId={workAri}" \
  --user "your-email@example.com:{API_TOKEN}" \
  --header "Accept: application/json"

The request acts as your user — the same permissions apply as when you are logged in to the Atlassian site.

Service account API tokens (Bearer auth)

Service account API tokens are scoped tokens created for automated, service-to-service integrations. Pass the token as a Bearer token in the Authorization header:

1
2
curl --request GET \
  --url "https://api.atlassian.com/ex/capacity-planning/{cloudId}/v1/contributions?contributorDataId={contributorAri}&workDataId={workAri}" \
  --header "Authorization: Bearer {SERVICE_ACCOUNT_API_TOKEN}" \
  --header "Accept: application/json"

When creating a service account API token, select the scopes your integration needs. See Authorization for the full list of available scopes.

OAuth 2.0

Use OAuth 2.0 (3LO) with granular scopes to access the Capacity Planning REST API from Connect or Forge apps, or any third-party integration registered in the Developer Console.

When requesting authorization, include the Capacity Planning scopes your app requires (see Authorization for the full list). Pass the OAuth access token as a Bearer token in the Authorization header:

1
2
curl --request GET \
  --url "https://api.atlassian.com/ex/capacity-planning/{cloudId}/v1/contributions?contributorDataId={contributorAri}&workDataId={workAri}" \
  --header "Authorization: Bearer {OAUTH_ACCESS_TOKEN}" \
  --header "Accept: application/json"

The request acts as the user who authorized the app — the same site and project permissions apply.

Finding your cloud ID

All API URLs include your site's cloudId. To find it:

1. Navigate to https://{your-site}.atlassian.net/_edge/tenant_info
2. Copy the cloudId value from the JSON response

Use this value in the URL path:

1
2
https://api.atlassian.com/ex/capacity-planning/{cloudId}/v1/...

Tenant context

The API is tenant-scoped — every request operates within a single Atlassian site identified by the cloudId in the URL path. You cannot access data across sites in a single request.