# Auth0

SureCloud connects to Auth0 to retrieve tenant security configuration, MFA policy status, user records, application access settings, and audit log events. This allows SureCloud to verify that customer-facing authentication is secured — confirming that MFA is enforced, that anomaly detection is enabled, and that administrative changes to the Auth0 tenant are captured in the log.

## Authentication and setup

Auth0 uses OAuth 2.0 with the client credentials grant for machine-to-machine API access. SureCloud uses a dedicated Auth0 Machine-to-Machine application scoped to read-only Management API permissions.

{% stepper %}
{% step %}

### Create a Machine-to-Machine application in Auth0

Log in to the Auth0 Dashboard. Navigate to **Applications → Applications → Create Application**. Select **Machine to Machine Applications** and name it `SureCloud CCM`. Click **Create**.
{% endstep %}

{% step %}

### Authorise the Management API with read-only scopes

On the application settings page, select **Auth0 Management API** from the authorised APIs dropdown. Under **Permissions**, add the following scopes: `read:users`, `read:clients`, `read:connections`, `read:tenant_settings`, `read:logs`, `read:roles`, `read:grants`, `read:anomaly_blocks`. Click **Authorise**.
{% endstep %}

{% step %}

### Enter the credentials in SureCloud

Navigate to **SureCloud → Integrations → Auth0 → Connect**. Enter your Auth0 **Domain** (e.g. `yourcompany.auth0.com` or `yourcompany.eu.auth0.com`), the **Client ID**, and the **Client Secret**. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the Client Secret securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **Auth0 → Applications → SureCloud CCM → Rotate Secret** and update it in **SureCloud → Integrations → Auth0 → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                       | Use Case                                                                                |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `GET /api/v2/tenant/settings`  | Retrieve tenant security settings including session lifetime and brute-force protection |
| `GET /api/v2/guardian/factors` | Retrieve MFA factor configuration and enforcement status                                |
| `GET /api/v2/users`            | Enumerate users including MFA enrolment status and last login                           |
| `GET /api/v2/clients`          | List applications and their grant types and token settings                              |
| `GET /api/v2/connections`      | Retrieve identity provider connections and their security configuration                 |
| `GET /api/v2/roles`            | Enumerate roles and their permission assignments                                        |
| `GET /api/v2/logs`             | Retrieve tenant audit log events for administrative activity evidence                   |
| `GET /api/v2/anomaly/blocks`   | Retrieve blocked IPs and users from anomaly detection                                   |

## Pagination

`GET /api/v2/users` and `GET /api/v2/logs` use checkpoint-based pagination. SureCloud uses the `from` parameter with the last log ID or user ID from each response, continuing until the result count falls below the page size.

```
GET /api/v2/logs?take=100&from=<last_log_id_from_previous_response>
```

`GET /api/v2/users` supports `page` and `per_page` parameters as an alternative.

## Required permissions / scopes

SureCloud requires a Machine-to-Machine application with the following Management API scopes:

| Scope                  | Purpose                                        |
| ---------------------- | ---------------------------------------------- |
| `read:users`           | Enumerate users and MFA enrolment status       |
| `read:clients`         | Read application configuration and grant types |
| `read:connections`     | Read identity provider connection settings     |
| `read:tenant_settings` | Read tenant-level security configuration       |
| `read:logs`            | Access audit log events                        |
| `read:roles`           | Read role and permission definitions           |
| `read:grants`          | Read OAuth grant records                       |
| `read:anomaly_blocks`  | Read anomaly detection block records           |

No write permissions are required.

## Polling frequency

| Data Type                                      | Interval       |
| ---------------------------------------------- | -------------- |
| Tenant security settings and MFA configuration | Every 24 hours |
| User records and MFA enrolment                 | Every 24 hours |
| Application and connection configuration       | Every 24 hours |
| Audit log events                               | Every 4 hours  |
| Anomaly detection blocks                       | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized or "invalid_client"</summary>

The Client ID or Client Secret is incorrect, or the application has not been authorised against the Management API. Confirm the application is authorised in **Auth0 → Applications → APIs → Auth0 Management API** and that the correct scopes are granted. Verify the domain, Client ID, and Client Secret in **SureCloud → Integrations → Auth0 → Edit Connection**.

</details>

<details>

<summary>User list returns empty despite users existing in Auth0</summary>

The `read:users` scope must be explicitly granted on the Management API authorisation. If the scope was omitted, the users endpoint will return empty or 403. Review the authorised scopes in **Auth0 → Applications → SureCloud CCM → APIs** and add `read:users` if missing.

</details>

<details>

<summary>Audit log returns only recent entries</summary>

Auth0 retains log data for a period dependent on your subscription tier (2 days on free, up to 30 days on paid plans, longer with the extended log retention add-on). SureCloud collects logs within the available retention window. For longer audit retention, enable extended log retention in Auth0 or export logs to an external SIEM.

</details>

<details>

<summary>Rate limit errors (429) during log collection</summary>

Auth0 Management API rate limits vary by endpoint and subscription tier. SureCloud throttles log collection to avoid hitting limits, but large tenants with high log volumes may encounter temporary 429 responses. SureCloud retries automatically on the next polling cycle.

</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/auth0.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.