Atlassian Opsgenie User Management API Guide

Auth method: API Key (GenieKey scheme)

Setup steps

1. Log in to Opsgenie as an Account Owner or Global Admin.
2. Navigate to Settings > App Settings > API Key Management.
3. Click 'Add New API Key', enter a name, and select access rights: Read, Create/Update, Delete, and/or Configuration Access.
4. Copy the generated key - it will not be shown again.
5. Pass the key in every request header as: Authorization: GenieKey .
6. For EU instance, use base URL https://api.eu.opsgenie.com instead.

Required scopes

Create User

• Method: POST
• URL: https://api.opsgenie.com/v2/users
• Watch out for: Requires Configuration Access on the API key. username must be a valid email and is immutable after creation.

Request example

curl -X POST 'https://api.opsgenie.com/v2/users' \
  -H 'Authorization: GenieKey <key>' \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","fullName":"Jane Doe","role":{"name":"User"},"locale":"en_US","timeZone":"UTC"}'

Response example

{
  "result": "Created",
  "data": {
    "id": "415ec30e-80ce-4219-b16e-0d4e5dc50f0a",
    "name": "[email protected]"
  },
  "took": 1.141,
  "requestId": "5469f0c6-dc71-4bf0-a417-d3792dda3417"
}

Get User

• Method: GET
• URL: https://api.opsgenie.com/v2/users/{identifier}
• Watch out for: identifier can be the user's UUID or username (email). Use ?expand=contact to include userContacts in the response.

Request example

curl -X GET 'https://api.opsgenie.com/v2/users/[email protected]?expand=contact' \
  -H 'Authorization: GenieKey <key>'

Response example

{
  "data": {
    "id": "f4df67fe-15cb-4c88-ad9c-a1a83a785fe6",
    "username": "[email protected]",
    "fullName": "jane doe",
    "role": {"id": "Admin", "name": "Admin"},
    "timeZone": "GMT",
    "locale": "en_US",
    "blocked": false,
    "verified": false
  }
}

List Users

• Method: GET
• URL: https://api.opsgenie.com/v2/users
• Watch out for: Falls under the 'Search' rate-limit domain (lower limits). Supports query param for field-based filtering (e.g., query=role:admin, query=fullName:doe).

Request example

curl -X GET 'https://api.opsgenie.com/v2/users?limit=50&offset=0&sort=fullName&order=asc&query=role:admin' \
  -H 'Authorization: GenieKey <key>'

Response example

{
  "totalCount": 8,
  "data": [{"id": "...", "username": "[email protected]", "fullName": "john doe", "role": {"name": "Admin"}}],
  "paging": {"next": "https://api.opsgenie.com/v2/users?limit=50&offset=50"},
  "took": 0.266
}

Update User (partial)

• Method: PATCH
• URL: https://api.opsgenie.com/v2/users/{identifier}
• Watch out for: PATCH is partial - only supplied fields are updated. username (email) cannot be changed via this endpoint. Requires Create/Update + Configuration Access rights.

Request example

curl -X PATCH 'https://api.opsgenie.com/v2/users/[email protected]' \
  -H 'Authorization: GenieKey <key>' \
  -H 'Content-Type: application/json' \
  -d '{"fullName": "Jane Smith", "role": {"name": "admin"}}'

Response example

{
  "result": "Updated",
  "data": {"id": "415ec30e-...", "name": "[email protected]"},
  "took": 0.049
}

Delete User

• Method: DELETE
• URL: https://api.opsgenie.com/v2/users/{identifier}
• Watch out for: Permanently deletes the user and all associated data. Requires Delete + Configuration Access rights. Cannot be undone.

Request example

curl -X DELETE 'https://api.opsgenie.com/v2/users/[email protected]' \
  -H 'Authorization: GenieKey <key>'

Response example

{
  "result": "Deleted",
  "took": 0.204,
  "requestId": "abc123"
}

Add Team Member

• Method: POST
• URL: https://api.opsgenie.com/v2/teams/{teamIdentifier}/members
• Watch out for: teamIdentifier can be team name or UUID; use teamIdentifierType=name or teamIdentifierType=id accordingly. Team-scoped API keys cannot manage members of other teams.

Request example

curl -X POST 'https://api.opsgenie.com/v2/teams/MyTeam/members?teamIdentifierType=name' \
  -H 'Authorization: GenieKey <key>' \
  -H 'Content-Type: application/json' \
  -d '{"user": {"username": "[email protected]"}, "role": "user"}'

Response example

{
  "result": "Added",
  "data": {"id": "c569c016-...", "name": "MyTeam"},
  "took": 3.67
}

Create Custom User Role

• Method: POST
• URL: https://api.opsgenie.com/v2/roles
• Watch out for: extendedRole must be one of the built-in roles (user, observer, stakeholder). Custom roles inherit rights from the base role and can grant or disallow specific rights.

Request example

curl -X POST 'https://api.opsgenie.com/v2/roles' \
  -H 'Authorization: GenieKey <key>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "ReadOnlyOps", "extendedRole": "user", "grantedRights": ["logs-page-access"]}'

Response example

{
  "result": "Created",
  "data": {"id": "187f70c4-...", "name": "ReadOnlyOps"},
  "took": 1.326
}

List Custom User Roles

• Method: GET
• URL: https://api.opsgenie.com/v2/roles
• Watch out for: Returns only custom roles, not built-in roles (Admin, User, Observer, Stakeholder).

Request example

curl -X GET 'https://api.opsgenie.com/v2/roles' \
  -H 'Authorization: GenieKey <key>'

Response example

{
  "data": [{"id": "187f70c4-...", "name": "ReadOnlyOps"}],
  "took": 0.076,
  "requestId": "fd6e3216-..."
}

• Rate limits: Opsgenie uses a Token Bucket Algorithm with rolling windows checked per minute and per second. Limits vary by subscription plan (Enterprise highest, Free lowest) and by request domain. User API and Team API fall under the 'Configuration' domain, which has lower limits than Alert or Integration domains. Exceeding limits returns HTTP 429. Rate limit state is returned in response headers on every request.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: Opsgenie provides rate limit state via HTTP response headers on every request. No Retry-After header is documented; official guidance recommends exponential backoff (2^attemptCount × 200ms). Configuration domain (User API, Team API, etc.) has lower limits than Alert/Integration domains. Optional per-integration fairness cap (10% of account limit per integration) can be enabled on request.
• Pagination method: offset
• Default page size: 20
• Max page size: 100
• Pagination pointer: limit / offset

• Webhooks available: Yes
• Webhook notes: Opsgenie supports outbound webhooks via its Webhook Integration. Webhooks fire on alert and incident lifecycle events and POST a JSON payload to a configured HTTPS endpoint. They are configured per-integration in the Opsgenie UI or via the Integration API, not as a standalone webhook subscription API.
• Alternative event strategy: For user lifecycle events (create/update/delete), no native webhook exists. Poll GET /v2/users on a schedule, or use SCIM provisioning from an IdP which handles lifecycle events via the IdP's own event system.
• Webhook events: alert-created, alert-acknowledged, alert-closed, alert-escalated, alert-assigned, alert-tagged, alert-note-added, incident-created, incident-resolved, incident-status-updated

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Atlassian Guard Standard subscription (~$4/user/month additional cost on top of Opsgenie plan). SSO must be configured before enabling SCIM.

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

• Supported operations: Create user (POST /Users), Get user (GET /Users/{id}), List users (GET /Users), Update user (PUT /Users/{id}), Patch user (PATCH /Users/{id}), Deactivate/delete user (DELETE /Users/{id}), Create group (POST /Groups), Get group (GET /Groups/{id}), List groups (GET /Groups), Update group members (PATCH /Groups/{id}), Delete group (DELETE /Groups/{id})

Limitations:

• Requires Atlassian Guard Standard subscription - not included in any Opsgenie plan by default.
• SSO must be configured before SCIM can be enabled.
• SCIM API keys expire after 1 year (enforced as of January 2025); annual rotation required.
• Default groups cannot be managed via SCIM - only IdP-synced groups.
• Batch sizes above 10,000 users in a group will suspend subsequent directory syncs.
• Groups with more than 20,000 users require Atlassian to enable a feature flag.
• SCIM provisions users at the Atlassian organization level, not directly at the Opsgenie product level; product access is granted via group-to-app assignment.
• Opsgenie reaches end of support April 5, 2027; new purchases stopped June 4, 2025. SCIM investment should account for migration to Jira Service Management or Compass.

Three provisioning patterns cover the majority of automation use cases. First, employee onboarding: POST /v2/users to create the account, then POST /v2/teams/{teamIdentifier}/members to assign the on-call team - note the user receives an invitation email and is not immediately active.

Second, offboarding: retrieve the user's UUID via GET /v2/users/{username}, audit and reassign any on-call schedules or escalation policies that reference them, then DELETE /v2/users/{identifier} - deletion is permanent and immediate, so schedule auditing is not optional. Third, bulk IdP sync via SCIM 2.

0: requires an Atlassian Guard Standard subscription (~$4/user/month additional) and SSO configured as a prerequisite; SCIM API keys expire annually as of January 2025 and must be rotated on a calendar schedule. Keep group batch sizes under 10,000 users to avoid suspending directory syncs.

Onboard a new employee

1. POST /v2/users with username (email), fullName, role, timeZone, locale to create the account.
2. POST /v2/teams/{teamIdentifier}/members to add the user to their on-call team with the appropriate team role (admin or user).
3. Optionally POST /v2/users/{id}/contacts via the Contact API to add SMS or voice notification contacts.
4. Verify the user appears in GET /v2/users?query=username:{email}.

Watch out for: The API key must have Create/Update + Configuration Access rights. The user will receive an invitation email from Opsgenie to set their password; they are not immediately active.

Offboard / deprovision a departing employee

1. GET /v2/users/{username} to confirm the user exists and retrieve their UUID.
2. Review and reassign any on-call schedules or escalation policies that reference this user before deletion.
3. DELETE /v2/users/{identifier} to permanently remove the user from Opsgenie.
4. If using SCIM, deactivating the user in the IdP will automatically trigger deprovisioning via PATCH /Users/{id} (active: false) or DELETE.

Watch out for: Deletion is permanent and immediate. If the user owns active on-call rotations, those rotations will break. Always audit schedules first. SCIM deactivation (active=false) is safer than hard delete as it preserves audit history.

Bulk-sync users from an IdP via SCIM

1. Subscribe to Atlassian Guard Standard and configure SSO for your Opsgenie organization.
2. In Atlassian Admin (admin.atlassian.com), go to Security > Identity Providers > Set up user provisioning.
3. Copy the SCIM base URL (https://api.atlassian.com/scim/directory/{directoryId}) and the SCIM API key - store both securely as the key is shown only once.
4. Configure your IdP (Okta, Entra ID, Google Workspace, OneLogin) with the SCIM base URL and API key; set Provisioning Mode to Automatic.
5. Assign users/groups to the Atlassian Cloud app in your IdP; the IdP will POST /Users for each new user and PATCH /Groups to sync group memberships.
6. In Atlassian Admin, assign the synced groups to Opsgenie product access to grant licenses.

Watch out for: SCIM API keys expire after 1 year; set a calendar reminder for rotation. Keep batch sizes under 10,000 users per group sync to avoid suspending the directory. SSO must be fully configured before enabling SCIM or provisioning will fail.

The User API's Configuration rate-limit domain carries lower limits than the Alert domain, and List Users falls under the Search domain which may be lower still - bulk operations will hit HTTP 429 faster than expected. No Retry-After header is returned; implement exponential backoff using the formula 2^attemptCount × 200ms per Atlassian's own guidance.

The username field (email) is immutable after creation and cannot be changed via the User API; email changes require SCIM or Atlassian account management. No native webhook exists for user lifecycle events - polling GET /v2/users on a schedule is the only API-native option for detecting changes outside of SCIM.

Finally, team-scoped API keys cannot perform account-level User API requests; always generate keys from Settings > API Key Management, not from a team integration.