Atlassian Confluence User Management API Guide

Auth method: OAuth 2.0 (3-legged for user context; API tokens via HTTP Basic for server/personal access)

Setup steps

1. Register an OAuth 2.0 app at https://developer.atlassian.com/console/myapps/
2. Select 'Confluence' as the product and add required scopes.
3. Use the authorization URL: https://auth.atlassian.com/authorize to obtain an authorization code.
4. Exchange the code for an access token at https://auth.atlassian.com/oauth/token.
5. For API token (Basic Auth): generate a token at https://id.atlassian.com/manage-profile/security/api-tokens and use as password with your Atlassian account email as username.
6. API tokens expire after 1 year (as of January 2025).

Required scopes

Get current user

• Method: GET
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/user/current
• Watch out for: Returns the authenticated user's profile. Requires a user-context OAuth token, not a service account token.

Request example

GET /wiki/rest/api/user/current
Authorization: Bearer {token}

Response example

{
  "accountId": "5b10a2844c20165700ede21g",
  "accountType": "atlassian",
  "email": "user@example.com",
  "publicName": "Jane Doe",
  "displayName": "Jane Doe"
}

Get user by accountId

• Method: GET
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/user?accountId={accountId}
• Watch out for: Email may be null if the user's profile visibility is set to private.

Request example

GET /wiki/rest/api/user?accountId=5b10a2844c20165700ede21g
Authorization: Bearer {token}

Response example

{
  "accountId": "5b10a2844c20165700ede21g",
  "accountType": "atlassian",
  "displayName": "Jane Doe",
  "email": "user@example.com"
}

Get group members

• Method: GET
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/group/{groupName}/member
• Watch out for: Uses v1 offset pagination (start/limit). Group name is case-sensitive.

Request example

GET /wiki/rest/api/group/confluence-users/member?limit=50
Authorization: Bearer {token}

Response example

{
  "results": [
    {"accountId": "abc123", "displayName": "Jane Doe"}
  ],
  "start": 0,
  "limit": 50,
  "size": 1
}

List groups

• Method: GET
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/group
• Watch out for: Returns all groups in the Confluence site. Use groupId (not name) for membership operations where possible.

Request example

GET /wiki/rest/api/group?limit=50
Authorization: Bearer {token}

Response example

{
  "results": [
    {"id": "group-id-1", "name": "confluence-users", "type": "group"}
  ],
  "start": 0,
  "limit": 50,
  "size": 1
}

Add user to group

• Method: POST
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/group/user
• Watch out for: Group name is passed as a query parameter. Requires write:confluence-groups scope.

Request example

POST /wiki/rest/api/group/user?name={groupName}
Content-Type: application/json
{"accountId": "5b10a2844c20165700ede21g"}

Response example

HTTP 201 Created
(empty body)

Remove user from group

• Method: DELETE
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/group/user?name={groupName}&accountId={accountId}
• Watch out for: Both groupName and accountId are required as query params. Cannot remove the last admin from a group.

Request example

DELETE /wiki/rest/api/group/user?name=confluence-users&accountId=5b10a2844c20165700ede21g
Authorization: Bearer {token}

Response example

HTTP 204 No Content

Get user's group memberships

• Method: GET
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/rest/api/user/memberof?accountId={accountId}
• Watch out for: Returns Confluence-level group memberships only, not Atlassian organization-level groups.

Request example

GET /wiki/rest/api/user/memberof?accountId=5b10a2844c20165700ede21g
Authorization: Bearer {token}

Response example

{
  "results": [
    {"id": "group-id-1", "name": "confluence-users"}
  ],
  "start": 0,
  "limit": 200,
  "size": 1
}

Search users (v2 API)

• Method: GET
• URL: https://api.atlassian.com/ex/confluence/{cloudId}/wiki/api/v2/spaces/{spaceId}/permissions
• Watch out for: User search uses CQL (Confluence Query Language). Direct user creation is not supported via Confluence REST API; use SCIM or Atlassian Admin APIs.

Request example

GET /wiki/rest/api/search/user?cql=type=user&limit=25
Authorization: Bearer {token}

Response example

{
  "results": [
    {"user": {"accountId": "abc123", "displayName": "Jane Doe"}}
  ],
  "start": 0,
  "limit": 25
}

• Rate limits: Atlassian enforces rate limits on Confluence Cloud REST APIs. Limits are not publicly documented with exact numbers per plan; Atlassian uses a request-cost model and may return HTTP 429 when limits are exceeded.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when rate limited. Atlassian recommends honoring the Retry-After header and using exponential backoff. Exact per-plan limits are not publicly documented.
• Pagination method: cursor
• Default page size: 25
• Max page size: 250
• Pagination pointer: cursor (v2 API); start + limit (v1 API)

• Webhooks available: Yes
• Webhook notes: Confluence Cloud supports webhooks for space and content events, but user lifecycle events (create/deactivate) are not natively available via Confluence webhooks. User provisioning events are handled at the Atlassian organization level.
• Alternative event strategy: Use Atlassian Admin API webhooks (https://developer.atlassian.com/cloud/admin/) for user lifecycle events, or poll the SCIM API for provisioning changes.
• Webhook events: user_created (organization-level, via Atlassian Admin API webhooks), user_deactivated (organization-level), group_created, group_updated, group_deleted, space_created, space_updated, page_created, page_updated

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Atlassian Guard Standard ($4/user/mo) or Enterprise plan (includes Guard Standard)

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

• Supported operations: GET /Users - list users, GET /Users/{userId} - get user, POST /Users - create user, PUT /Users/{userId} - replace user, PATCH /Users/{userId} - update user (activate/deactivate), DELETE /Users/{userId} - delete user, GET /Groups - list groups, GET /Groups/{groupId} - get group, POST /Groups - create group, PUT /Groups/{groupId} - replace group, PATCH /Groups/{groupId} - update group members, DELETE /Groups/{groupId} - delete group

Limitations:

• Requires Atlassian Guard Standard subscription or Enterprise plan.
• SSO must be configured before enabling SCIM provisioning.
• SCIM API tokens expire after 1 year (as of January 2025); must be rotated manually.
• SCIM manages users at the Atlassian organization level, not per-product.
• Deprovisioning via SCIM deactivates the Atlassian account across all products, not just Confluence.
• Supported IdPs with native connectors: Okta, Microsoft Entra ID (Azure AD), Google Workspace.
• Custom SCIM integrations must use the Atlassian SCIM endpoint directly.
• Group push syncs group membership but does not automatically grant Confluence product access; product access must be configured separately via group-to-product mapping.

Stitchflow connects to Confluence via an MCP server with ~100 deep IT/identity integrations, enabling automated provisioning workflows that the Confluence REST API alone cannot complete end-to-end.

Provisioning a new user requires SCIM: POST to https://api.atlassian.com/scim/directory/{directoryId}/Users with userName, name, emails, and active: true. After creation, PATCH the target group to add the user as a member. Group membership alone does not grant Confluence product access - the group must also be mapped to the Confluence product in Atlassian Admin separately. SCIM tokens carry the same 1-year expiration as API tokens.

Deprovisioning via SCIM (PATCH active: false) deactivates the user's entire Atlassian account across all products - Jira, Confluence, and any other linked product - not Confluence in isolation. Content and audit history are retained. If full data removal is required, a separate deletion step must be performed in admin.atlassian.com after deactivation; SCIM deactivation alone does not delete the account or its personal data.

For group membership reads, use GET /wiki/rest/api/group/{groupName}/member with offset pagination (start/limit). Group names are case-sensitive. Email fields in user objects may return null if the user has set profile visibility to private - build null-handling into any pipeline that relies on email as an identifier.

Provision a new user and add to a Confluence group via SCIM

1. Ensure Atlassian Guard Standard is active and SCIM is configured for your directory.
2. POST to https://api.atlassian.com/scim/directory/{directoryId}/Users with userName, name, emails, and active=true.
3. Note the returned SCIM user id.
4. PATCH https://api.atlassian.com/scim/directory/{directoryId}/Groups/{groupId} with op:add, path:members, value:[{value: scimUserId}] to add the user to a group.
5. In Atlassian Admin, ensure the target group is mapped to the Confluence product to grant product access.

Watch out for: SCIM token expires after 1 year. Group membership alone does not grant Confluence access; product access mapping must be configured in Atlassian Admin.

Deprovision a user (deactivate via SCIM)

1. Retrieve the user's SCIM id by GET https://api.atlassian.com/scim/directory/{directoryId}/Users?filter=userName eq "user@example.com".
2. PATCH https://api.atlassian.com/scim/directory/{directoryId}/Users/{userId} with {"Operations":[{"op":"replace","path":"active","value":false}]}.
3. Confirm the user's Atlassian account is deactivated (they lose access to all Atlassian products).

Watch out for: Deactivation is organization-wide, not Confluence-specific. The user's content and history are retained.

List all members of a Confluence group via REST API

1. Authenticate with OAuth 2.0 or API token (Basic Auth).
2. GET /wiki/rest/api/group to find the target group name or ID.
3. GET /wiki/rest/api/group/{groupName}/member?limit=50 to retrieve the first page of members.
4. Increment the start parameter by limit and repeat until size < limit to paginate through all members.

Watch out for: v1 API uses offset pagination. Group names are case-sensitive. Email fields may be null for users with private profile visibility.

The most significant API trap is the gap between group membership and product access. Adding a user to a Confluence group via the API or SCIM does not automatically grant them Confluence product access. Product access must be configured as a separate group-to-product mapping in Atlassian Admin.

Automations that skip this step will provision users who appear in groups but cannot log in to Confluence.

SCIM deprovisioning scope is a second high-risk area. Because SCIM operates at the Atlassian organization level, deactivating a user via SCIM removes access to every Atlassian product simultaneously.

There is no SCIM operation to remove Confluence access only while preserving Jira access - that requires manual product access adjustment in Atlassian Admin before or after SCIM deactivation.

Pagination strategy mismatch will silently truncate results in mixed-version implementations. The v1 API uses offset pagination; the v2 API uses cursor-based pagination. Using offset parameters against v2 endpoints, or cursor parameters against v1 endpoints, will not return errors in all cases but will produce incomplete result sets.

Audit any existing integration that queries both API versions to confirm pagination logic is version-specific.