# Atlassian access

SureCloud connects to Atlassian Access (now part of Atlassian Guard) to retrieve managed account records, organisation security policy configuration, identity provider (IdP) connection status, and audit log events. This allows SureCloud to verify that centralised SSO is active for your Atlassian products, that security policies such as enforced SSO and two-step verification are configured, and that administrative changes are captured in the organisation audit log.

## Authentication and setup

Atlassian Access authenticates API requests using an API key associated with an Atlassian organisation admin account.

{% stepper %}
{% step %}
**Generate an API key in Atlassian Admin**

Log in to the Atlassian admin console at [admin.atlassian.com](https://admin.atlassian.com/). Navigate to **Settings → API keys** and click **Create API key**. Name it `SureCloud CCM` and set an expiry date. Copy the **API Key** and note the associated **Organisation ID** shown on the page.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Atlassian Access → Connect**. Enter the **Organisation ID** and paste the **API Key**. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Atlassian API keys have a maximum lifetime of 1 year. SureCloud will alert you when a key is approaching its expiry. Generate a new key before it expires and update it in **SureCloud → Integrations → Atlassian Access → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                     | Use Case                                                                                    |
| -------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `GET /admin/v1/orgs/{orgId}`                 | Retrieve organisation details and security policy status                                    |
| `GET /admin/v1/orgs/{orgId}/users`           | Enumerate managed Atlassian accounts across the organisation                                |
| `GET /admin/v1/orgs/{orgId}/policies`        | Retrieve security policies including SSO enforcement and two-step verification requirements |
| `GET /admin/v1/orgs/{orgId}/domains`         | List verified domains under organisational control                                          |
| `GET /admin/v1/orgs/{orgId}/audit-log`       | Retrieve organisation-level audit log events                                                |
| `GET /admin/v1/orgs/{orgId}/directory/users` | Retrieve directory-synced users and their provisioning status                               |

## Pagination

`GET /admin/v1/orgs/{orgId}/users` and `GET /admin/v1/orgs/{orgId}/audit-log` use cursor-based pagination. SureCloud uses the `cursor` value from the `links.next` field in each response, continuing until no `next` link is present.

```
GET /admin/v1/orgs/{orgId}/users?cursor=<value_from_previous_response>
```

## Required permissions

SureCloud requires an Atlassian organisation API key for an account with **Organisation Admin** access. This provides:

* Read access to all managed accounts
* Read access to security policies and IdP configuration
* Read access to verified domains
* Read access to the organisation audit log

No write, policy-change, or user-management permissions are required.

## Polling frequency

| Data Type                     | Interval       |
| ----------------------------- | -------------- |
| Managed account inventory     | Every 24 hours |
| Security policy configuration | Every 24 hours |
| Domain verification status    | Every 24 hours |
| Audit log events              | Every 6 hours  |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The API key is invalid, has expired, or the Organisation ID is incorrect. Navigate to **Atlassian Admin → Settings → API keys**, confirm the key is active and within its validity period, and verify the Organisation ID. Generate a new key if necessary and update both values in **SureCloud → Integrations → Atlassian Access → Edit Connection**.

</details>

<details>

<summary>User list does not include all Atlassian accounts in the organisation</summary>

`GET /admin/v1/orgs/{orgId}/users` only returns accounts claimed under the organisation (i.e. accounts whose email domains are verified and managed by the organisation). Unmanaged Atlassian accounts — those using personal email domains not verified in your organisation — will not appear. Review domain verification in **Atlassian Admin → Domains**.

</details>

<details>

<summary>Security policies endpoint returns empty</summary>

Atlassian Access (Guard) security policies require an active Atlassian Access subscription. If your organisation does not have Atlassian Access or Atlassian Guard enabled, the policies endpoint will return empty. Confirm the subscription status in **Atlassian Admin → Billing**.

</details>

<details>

<summary>Audit log returns limited history</summary>

Atlassian's organisation audit log retention period depends on your Atlassian Access plan tier. SureCloud collects within the available retention window. For extended audit history, consider exporting audit logs to an external SIEM.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/atlassian-access.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.