Atlassian Statuspage User Management API Guide

Auth method: API Key - passed as Authorization header (value: 'OAuth ') or as query param 'api_key='. The header value uses the literal string 'OAuth' as a prefix per official docs, but this is a static API key, not an OAuth 2.0 flow.

Setup steps

1. Log in to https://manage.statuspage.io
2. Click your avatar (bottom-left) > API info
3. Click 'Create key', enter a descriptive name, copy the key immediately (as of Jan 31 2026 keys are no longer re-displayable after creation)
4. Pass the key in requests as: -H 'Authorization: OAuth ' or as ?api_key=
5. Note: only account owners can create/delete keys; keys are org-scoped and remain active even if the creating user's access is revoked

List page access users

• Method: GET
• URL: https://api.statuspage.io/v1/pages/{page_id}/page_access_users
• Watch out for: Unpaginated calls to this endpoint are rate-limited to 1 req/min. Always pass ?page=1&per_page=100 to use the 60 req/min paginated limit.

Request example

curl 'https://api.statuspage.io/v1/pages/{page_id}/page_access_users?page=1&per_page=100' \
  -H 'Authorization: OAuth your-api-key-goes-here'

Response example

[
  {
    "id": "abc123",
    "email": "user@example.com",
    "external_login": null,
    "page_id": "xyz789",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

Get a single page access user

• Method: GET
• URL: https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{page_access_user_id}
• Watch out for: Returns 404 if the user_id does not exist on the specified page.

Request example

curl 'https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{user_id}' \
  -H 'Authorization: OAuth your-api-key-goes-here'

Response example

{
  "id": "abc123",
  "email": "user@example.com",
  "external_login": null,
  "page_access_group_ids": [],
  "page_id": "xyz789"
}

Add (create) a page access user

• Method: POST
• URL: https://api.statuspage.io/v1/pages/{page_id}/page_access_users
• Watch out for: Page must be switched to audience-specific type before page_access_users endpoints have any effect. Returns 409 on duplicate email.

Request example

curl 'https://api.statuspage.io/v1/pages/{page_id}/page_access_users' \
  -H 'Authorization: OAuth your-api-key-goes-here' \
  -d 'page_access_user[email]=user@example.com' \
  -d 'page_access_user[external_login]=ext_id'

Response example

{
  "id": "newuser456",
  "email": "user@example.com",
  "page_id": "xyz789",
  "created_at": "2025-01-01T00:00:00Z"
}

Update a page access user

• Method: PATCH
• URL: https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{page_access_user_id}
• Watch out for: PUT is also available and behaves identically to PATCH for this resource.

Request example

curl 'https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{user_id}' \
  -H 'Authorization: OAuth your-api-key-goes-here' \
  -X PATCH \
  -d 'page_access_user[email]=new@example.com' \
  -d 'page_access_user[page_access_group_ids][]=grp_id'

Response example

{
  "id": "abc123",
  "email": "new@example.com",
  "page_access_group_ids": ["grp_id"]
}

Delete a page access user

• Method: DELETE
• URL: https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{page_access_user_id}
• Watch out for: No response body on success. Returns 404 if user not found.

Request example

curl 'https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{user_id}' \
  -H 'Authorization: OAuth your-api-key-goes-here' \
  -X DELETE

Response example

HTTP 204 No Content

Get user's org-level permissions

• Method: GET
• URL: https://api.statuspage.io/v1/organizations/{organization_id}/permissions/{user_id}
• Watch out for: Only applicable to internal team members (not page_access_users). Requires RBAC to be enabled on the page.

Request example

curl 'https://api.statuspage.io/v1/organizations/{org_id}/permissions/{user_id}' \
  -H 'Authorization: OAuth your-api-key-goes-here'

Response example

{
  "user_id": "usr_abc",
  "pages": {
    "page_id_1": ["role_a", "role_b"]
  }
}

Update user's org-level permissions

• Method: PUT
• URL: https://api.statuspage.io/v1/organizations/{organization_id}/permissions/{user_id}
• Watch out for: Omitting a page from the payload removes the user's access to that page entirely. Non-RBAC pages should map to an empty hash.

Request example

curl 'https://api.statuspage.io/v1/organizations/{org_id}/permissions/{user_id}' \
  -H 'Authorization: OAuth your-api-key-goes-here' \
  -X PUT \
  -d 'permissions[page_id_1][]=role_a'

Response example

{
  "user_id": "usr_abc",
  "pages": { "page_id_1": ["role_a"] }
}

Get components for a page access user

• Method: GET
• URL: https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{page_access_user_id}/components
• Watch out for: Also supports PATCH/PUT/POST/DELETE sub-endpoints to add, replace, or remove component visibility for the user.

Request example

curl 'https://api.statuspage.io/v1/pages/{page_id}/page_access_users/{user_id}/components' \
  -H 'Authorization: OAuth your-api-key-goes-here'

Response example

[
  { "id": "comp_abc", "name": "API", "status": "operational" }
]

• Rate limits: Manage API (authenticated): 60 requests per minute on a rolling window for paginated requests. Unpaginated GET requests to page_access_users and components endpoints are limited to 1 request per minute. Status API (public, read-only): not rate limited.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 420 and HTTP 429 are both used for rate-limit responses depending on the API service version; implement handling for both. A Retry-After header is included in rate-limit responses. Strongly recommended to use paginated GET requests (?page=1&per_page=100) to avoid the 1 req/min unpaginated limit on page_access_users.
• Pagination method: offset
• Default page size: 100
• Max page size: 100
• Pagination pointer: page (offset index, 1-based) + per_page (page size). Exception: /pages/{page_id}/subscribers uses 'page' + 'limit' instead of 'per_page'.

• Webhooks available: Yes
• Webhook notes: Statuspage supports outbound subscriber webhooks. End users (subscribers) can register a webhook URL to receive POST notifications when incidents are created/updated/resolved or when component statuses change. These are subscriber-facing notification webhooks, not management-plane event webhooks for admin automation.
• Alternative event strategy: For management-plane automation, use the authenticated REST API (polling) or integrate via PagerDuty, Opsgenie, or Jira Service Management integrations.
• Webhook events: incident.create, incident.update, incident.resolve, component_update (status change)

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Atlassian Guard Standard subscription (formerly Atlassian Access). SSO must be configured before enabling SCIM. Guard is billed per managed user (~$3–4/user/month) across the entire Atlassian organization.

• Endpoint: https://api.atlassian.com/scim/directory/{directoryId}

• Supported operations: Create user (POST /Users), Get user (GET /Users/{userId}), List users (GET /Users), Update user (PUT /Users/{userId}), Patch user (PATCH /Users/{userId}), Deactivate user (PATCH /Users/{userId} active=false), Create group (POST /Groups), Get group (GET /Groups/{groupId}), List groups (GET /Groups), Update group membership (PATCH /Groups/{groupId})

Limitations:

• Group sync is NOT available for Statuspage specifically; group sync is only available for Jira and Confluence instances
• SCIM API keys expire after 1 year (enforced as of January 2025); annual rotation is mandatory
• SSO must be configured as a prerequisite before SCIM can be enabled
• SCIM base URL and API key are shown only once at creation time - must be copied immediately
• Default groups (e.g., 'org-admins', 'atlassian-addons-admin') cannot be managed via SCIM
• Updating a user's email address must be done via the SCIM provisioning API, not the Atlassian user management API
• Site roles cannot be managed via SCIM API
• Provisioned users have no product access by default until explicitly granted via group-based app access configuration

Provisioning an audience-specific page viewer with component scoping: The target page must be set to audience-specific type before any page_access_users endpoint has effect.

POST to /v1/pages/{page_id}/page_access_users with email (and optionally external_login), then PATCH the user record to assign page_access_group_ids, then PATCH /components sub-endpoint to restrict component visibility.

Calls to this endpoint on non-audience-specific pages return no error but have no visible effect - a silent failure mode.

Bulk-listing page access users: Always paginate with ?page=1&per_page=100. Omitting pagination parameters triggers a separate rate-limit bucket of 1 request/minute on the page_access_users and components endpoints. The paginated path uses the standard 60 requests/minute rolling window. Iterate until a response returns fewer than 100 results.

SCIM provisioning via Atlassian Guard: SSO (SAML) must be configured before SCIM can be enabled. The SCIM base URL and API key are shown only once at setup - copy immediately. Configure your IdP with Create Users, Update User Attributes, and Deactivate Users enabled. Critical caveat: group sync does not apply to Statuspage. Statuspage team member access and page permissions must still be managed via the Manage API or manually after SCIM provisions the Atlassian account.

Provision an audience-specific page viewer and restrict their component visibility

1. Ensure the target page is set to 'audience-specific' type in Statuspage settings
2. POST /v1/pages/{page_id}/page_access_users with email and optional external_login
3. Optionally create or retrieve a page_access_group via GET /v1/pages/{page_id}/page_access_groups
4. PATCH /v1/pages/{page_id}/page_access_users/{user_id} with page_access_group_ids[] to assign the user to a group
5. Use PATCH /v1/pages/{page_id}/page_access_users/{user_id}/components to set which components the user can see

Watch out for: If the page is not audience-specific, all page_access_users API calls will have no visible effect on the page.

Bulk-list all page access users with pagination

1. Start with GET /v1/pages/{page_id}/page_access_users?page=1&per_page=100
2. Check if the response contains exactly 100 results; if so, increment page and repeat
3. Continue until a response returns fewer than 100 results (last page)

Watch out for: Omitting pagination parameters triggers the 1 req/min unpaginated rate limit. Always include both page and per_page parameters.

Automate team member provisioning via SCIM (Atlassian Guard)

1. Subscribe to Atlassian Guard Standard at admin.atlassian.com
2. Configure SSO (SAML) for the Atlassian organization - required before SCIM can be enabled
3. Go to Security > User security > Identity providers, select your IdP directory, click 'Set up user provisioning'
4. Copy the SCIM base URL (https://api.atlassian.com/scim/directory/{directoryId}) and API key immediately - they are shown only once
5. Configure your IdP (Okta, Entra ID, Google Workspace) with the SCIM base URL and bearer token
6. Enable Create Users, Update User Attributes, and Deactivate Users in the IdP provisioning settings
7. Note: group sync will NOT apply to Statuspage; only user-level provisioning is supported
8. Set a calendar reminder to rotate the SCIM API key before its 1-year expiry

Watch out for: Group sync is unavailable for Statuspage via SCIM. Statuspage team member access and page permissions must still be managed manually or via the Statuspage Manage API.

The API has three compounding gotchas that are not obvious from the documentation surface. First, page_access_users endpoints are scoped exclusively to audience-specific pages; they silently do nothing on public or private pages, which means integration tests against a non-audience-specific page will pass without provisioning anyone.

Second, omitting page and per_page query parameters on list calls drops the rate limit from 60 req/min to 1 req/min - a 60x degradation that will not surface until production load hits.

Third, both HTTP 420 and HTTP 429 are returned for rate-limit errors depending on API service version; handling only 429 will cause silent retry failures on older endpoints.

On the SCIM path: group sync is unavailable for Statuspage, meaning IdP group membership changes do not propagate to Statuspage page permissions. Teams that assume full lifecycle parity with Jira or Confluence SCIM behavior will find Statuspage requires a separate management layer.

The one-year SCIM API key expiry (mandatory since January 2025) with no automated warning is an additional operational dependency that must be tracked externally.

API keys remain active after the creating user's Statuspage access is revoked. Any key rotation or audit process must account for orphaned keys tied to departed team members, as these keys retain full org-scoped read/write access indefinitely until explicitly deleted.