Troubleshooting Integrations and Connectors

Connector shows as Disconnected

Symptom: A connector in the Integrations or Connectors page shows a status of Disconnected or Unhealthy, even though it was connected previously.

1. 1

   Run the Test Connection health check

   Open the connector detail page and click Test Connection. This runs a live connectivity check and returns a specific error message explaining why the connector is failing. Note the error before proceeding.

2. 2

   Check whether credentials have expired

   OAuth tokens, API keys, and service account passwords all expire on schedules set by the source system. If the error says 'token expired', 'unauthorized', or 'invalid credentials', the connector needs to be re-authenticated.

3. 3

   Check if the source service is experiencing an outage

   Visit the status page of the connected service (e.g., status.azure.com for Entra ID, githubstatus.com for GitHub) to rule out a service-wide outage. If the service is down, wait for it to recover.

4. 4

   Re-authenticate the connector

   Click Reconnect or Re-authenticate on the connector detail page. Follow the OAuth or API key entry flow to issue fresh credentials. For OAuth connectors, you will be redirected to the source system's login page.

5. 5

   Run Test Connection again after re-authenticating

   After completing re-authentication, run Test Connection again to confirm the connector returns a healthy status. If it still fails, the problem may be permissions-related rather than credential expiry.

6. 6

   Check for IP allowlist or network access restrictions

   Some services restrict API access by IP address. If your connector was previously allowed but the Nuxari API's outbound IP address has changed, the source service may be blocking requests. Update the source service's IP allowlist with the current Nuxari API IPs (available from Nuxari support).

Credentials expired or revoked

Symptom:The connector's health check returns "401 Unauthorized", "Access token expired", or "API key revoked". The connector was previously healthy.

1. 1

   For OAuth connectors: re-authenticate through the OAuth flow

   Click Reconnect on the connector detail page. You will be redirected to the source system's OAuth login page. Complete authentication and grant the requested permissions. Nuxari will receive a new access and refresh token.

2. 2

   For API key connectors: generate a new key in the source system

   Log into the source system, navigate to API keys or developer settings, and generate a new key with the same scopes as the previous one. Copy the new key and paste it into the connector's credential field in Nuxari.

3. 3

   For service account connectors: reset the service account password

   If the connector uses a service account with a password, reset the password in the source system's user directory. Update the connector configuration in Nuxari with the new password.

4. 4

   Verify the service account or app registration has not been deleted

   If credentials are rejected but you have not changed the password or rotated the key, the underlying service account or application registration may have been deleted by an admin. Verify it still exists in the source system.

5. 5

   Test connection and confirm healthy status

   After updating credentials, run Test Connection in Nuxari. Confirm the status returns healthy before closing the connector settings.

GitHub connector issues

Symptom:The GitHub connector fails to connect, returns incorrect data, or reports "Repository access denied" or "Organization membership not readable".

1. 1

   Verify the GitHub App is installed on your organization

   The Nuxari GitHub App must be installed on your GitHub organization (not just your personal account). Go to your GitHub organization's Settings > Installed GitHub Apps and confirm Nuxari is listed. If not, initiate the installation from the connector setup page.

2. 2

   Check which repositories the app has access to

   In GitHub organization settings, find the Nuxari app and click Configure. Under Repository access, ensure the app has access to the repositories required by your governance templates — either 'All repositories' or the specific ones selected.

3. 3

   Confirm the connecting user is an organization admin

   Installing and authorizing GitHub Apps requires organization admin privileges. If a non-admin attempted to connect the GitHub connector, the resulting token may have limited permissions. Reconnect using an account with admin access.

4. 4

   Check for GitHub SAML SSO requirement

   If your GitHub organization requires SAML SSO, OAuth tokens and personal access tokens must be authorized for SAML SSO use. In GitHub, go to Settings > Personal access tokens (or the app settings) and authorize the token for your SSO-protected organization.

5. 5

   Verify GitHub API rate limits are not exhausted

   GitHub's REST API has rate limits. If Nuxari is running frequent evaluations, it may hit the limit temporarily. Check the connector detail page for rate limit warnings. If limits are exhausted regularly, consider reducing evaluation frequency.

Microsoft Entra connector issues

Symptom:The Entra ID connector fails to authenticate, returns "AADSTS" error codes, or reports that it cannot read user or group data.

1. 1

   Verify the app registration exists in the correct tenant

   In the Azure portal, go to Azure Active Directory > App registrations and confirm the Nuxari app registration exists in the correct tenant. If multiple tenants are in use, ensure you registered the app in the tenant that contains the users and groups you want to govern.

2. 2

   Confirm admin consent has been granted for all required API permissions

   In the app registration, go to API permissions. Each Microsoft Graph permission required by Nuxari should show a green checkmark under 'Admin consent required'. If any permissions show 'Not granted', an Azure global admin must click 'Grant admin consent for [tenant]'.

3. 3

   Check the client secret expiry

   In the app registration, go to Certificates & secrets. Note the expiry date of the client secret being used. If it has expired, create a new secret, copy its value immediately (it is shown only once), and update the connector configuration in Nuxari.

4. 4

   Verify the tenant ID and client ID in the connector configuration

   In Nuxari, open the Entra ID connector settings and confirm the Tenant ID and Client ID match what is shown in the Azure app registration overview page. A single character mismatch will cause all authentication attempts to fail.

5. 5

   Check for Conditional Access policies blocking the service principal

   Azure Conditional Access policies can block non-human (service principal) sign-ins. Work with your Azure admin to confirm the Nuxari service principal is excluded from any policies that require MFA, compliant devices, or specific IP locations.

Okta connector issues

Symptom:The Okta connector returns "Invalid API token", "403 Forbidden", or stops returning user data after a period of normal operation.

1. 1

   Verify the Okta API token is still active

   In Okta, go to Security > API > Tokens and confirm the token used by Nuxari is listed and active. Okta API tokens do not expire on a schedule but can be revoked manually or when the creating user's account is deactivated.

2. 2

   Check that the token owner's account is active

   Okta API tokens are tied to the user account that created them. If that user has been deactivated or deleted, the token is automatically invalidated. Create a new token using a dedicated service account, not a personal user account.

3. 3

   Verify the Okta domain URL in the connector configuration

   The Okta domain must be your full Okta subdomain — for example, company.okta.com or company.oktapreview.com. Do not include https:// or a trailing slash. Verify this matches the domain in your Okta admin console.

4. 4

   Review the token's permission scope

   Okta API tokens inherit the permissions of the user who created them. If the token creator does not have the Read Users and Groups permission in Okta, the connector will return 403 errors for those resources. Use a token created by a Read-Only Admin or Super Admin.

Google Workspace connector issues

Symptom:The Google Workspace connector returns "Insufficient permissions", "Domain-wide delegation not configured", or fails to enumerate users.

1. 1

   Confirm domain-wide delegation is configured for the service account

   Google Workspace connectors typically use a service account with domain-wide delegation. In Google Workspace Admin Console, go to Security > API controls > Domain-wide delegation and verify the Nuxari service account client ID is listed with the required OAuth scopes.

2. 2

   Verify the impersonation email is correct

   Domain-wide delegation requires impersonating a real admin user's email address in your domain. Confirm the email address configured in Nuxari's Google Workspace connector settings belongs to an active Google Workspace admin account.

3. 3

   Check that the required OAuth scopes are included in the delegation

   The delegated scopes in Google Admin must include the exact scopes Nuxari needs, such as https://www.googleapis.com/auth/admin.directory.user.readonly and https://www.googleapis.com/auth/admin.directory.group.readonly. Missing or mistyped scopes cause 403 errors.

4. 4

   Re-upload the service account key file if it has been rotated

   If the service account key has been rotated in GCP, download the new JSON key file and upload it in the Nuxari connector configuration. The old key file will no longer be accepted after rotation.

Integration test fails

Symptom:Clicking "Test Connection" on any connector returns a failure, a timeout, or an error code, but you believe the credentials are correct.

1. 1

   Read the error message carefully

   The test result includes an error code or message from the source system. 401 means authentication failed. 403 means authenticated but not authorized. 404 can mean the API endpoint URL is wrong. Timeout means a network path issue. Use the specific error to guide your next step.

2. 2

   Confirm credentials were saved before testing

   If you are on the connector setup page and just entered credentials, ensure you clicked Save before clicking Test Connection. Some connector forms require an explicit save step before the test uses the new values.

3. 3

   Check Nuxari's system status

   If multiple connectors are all failing at once, there may be a Nuxari-side issue. Check the Nuxari status page or contact support to confirm all systems are operational.

4. 4

   Try the test again after 5 minutes

   Transient errors from external APIs (rate limits, brief outages) can cause test failures that resolve on their own. Wait 5 minutes and retry before escalating.

5. 5

   Contact Nuxari support with the error details

   If the test consistently fails with a specific error code and you cannot resolve it using the steps above, contact Nuxari support. Provide the connector type, the error message, and your workspace ID.