> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenID & OAuth

> Start SSO logins and integration OAuth flows for Confluence and SharePoint.

<Warning>
  **Upcoming release — Zylon 1.58**

  These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the [1.57 documentation](/en/v1.57/overview).
</Warning>

Use these endpoints to initiate OAuth/OpenID flows. Login endpoints are browser-oriented and return redirects; callback endpoints receive the provider response.

> Integrations must be enabled before you use their OAuth endpoints. See the operator guides for [Confluence](/en/v1.58/operator-manual/knowledge-base/confluence) and [SharePoint](/en/v1.58/operator-manual/knowledge-base/sharepoint).

## Basic request and response

Start a login flow by calling a provider login endpoint and following the redirect.

### User SSO login redirects

<Tabs>
  <Tab title="Google login">
    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/auth/google/login"
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...
      ```
    </Accordion>
  </Tab>

  <Tab title="Microsoft login">
    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/auth/microsoft/login"
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...
      ```
    </Accordion>
  </Tab>
</Tabs>

### Integration OAuth login redirects

Use `project_id` to create a project integration, or omit it to create an organization integration as an `AppAdmin` or higher. The optional `connector_name` sets its display name.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `project_id` | No | Project that will own the integration. Omit it for an organization integration. |
  | Query | `connector_name` | No | Display name for the new integration artifact. |
</Accordion>

<Tabs>
  <Tab title="Confluence login">
    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/confluence/login?project_id={projectID}&connector_name=Confluence" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://auth.atlassian.com/authorize?client_id=...&redirect_uri=...
      ```
    </Accordion>
  </Tab>

  <Tab title="SharePoint login">
    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/sharepoint/login?project_id={projectID}&connector_name=SharePoint" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...
      ```
    </Accordion>
  </Tab>
</Tabs>

### Login with a specific integration instance

Pass `integration_artifact_id` to replace the OAuth credentials of an existing integration artifact. Include `project_id` when the integration belongs to a project.

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Query | `integration_artifact_id` | Yes | Existing integration artifact whose OAuth credentials will be replaced. |
  | Query | `project_id` | Conditional | Project that owns the integration. Include it for a project integration. |
</Accordion>

<Tabs>
  <Tab title="Confluence instance">
    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/confluence/login?project_id={projectID}&integration_artifact_id={integrationArtifactID}" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://auth.atlassian.com/authorize?client_id=...&state=conf_8a7b6c5d4e3f2a1b
      ```
    </Accordion>
  </Tab>

  <Tab title="SharePoint instance">
    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/sharepoint/login?project_id={projectID}&integration_artifact_id={integrationArtifactID}" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&state=sp_1c2d3e4f5a6b7c8d
      ```
    </Accordion>
  </Tab>
</Tabs>

### Refresh an integration token

<Accordion title="Endpoint parameters">
  | Type | Name | Required | Notes |
  | - | - | - | - |
  | Path | `integrationArtifactID` | Yes | Integration artifact to refresh. |
</Accordion>

<Tabs>
  <Tab title="Confluence refresh">
    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/integration/confluence/refresh_token" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      "ok"
      ```
    </Accordion>
  </Tab>

  <Tab title="SharePoint refresh">
    ```bash theme={null}
    curl -X POST "https://{BASE_URL}/api/v1/app/artifact/{integrationArtifactID}/integration/sharepoint/refresh_token" \
      -H "Authorization: Bearer {API_TOKEN}" \
      -H "x-org: {org_slug}"
    ```

    <Accordion title="Example response">
      ```json theme={null}
      "ok"
      ```
    </Accordion>
  </Tab>
</Tabs>

### Callback endpoints

<Tabs>
  <Tab title="Microsoft callback">
    <Accordion title="Endpoint parameters">
      | Type | Name | Required | Notes |
      | - | - | - | - |
      | Query | `code` | Yes | OAuth authorization code. |
      | Query | `state` | Yes | OAuth state value returned by the provider. |
    </Accordion>

    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/auth/microsoft/callback?code=...&state=..."
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://{BASE_URL}/app/login/success
      ```
    </Accordion>
  </Tab>

  <Tab title="Confluence callback">
    <Accordion title="Endpoint parameters">
      | Type | Name | Required | Notes |
      | - | - | - | - |
      | Query | `code` | Yes | OAuth authorization code. |
      | Query | `state` | Yes | OAuth state value returned by the provider. |
    </Accordion>

    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/confluence/callback?code=...&state=..."
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://{BASE_URL}/app/integrations/confluence
      ```
    </Accordion>
  </Tab>

  <Tab title="SharePoint callback">
    <Accordion title="Endpoint parameters">
      | Type | Name | Required | Notes |
      | - | - | - | - |
      | Query | `code` | Yes | OAuth authorization code. |
      | Query | `state` | Yes | OAuth state value returned by the provider. |
    </Accordion>

    ```bash theme={null}
    curl -i "https://{BASE_URL}/api/v1/app/artifact/integration/sharepoint/callback?code=...&state=..."
    ```

    <Accordion title="Example response">
      ```text theme={null}
      HTTP/1.1 302 Found
      Location: https://{BASE_URL}/app/integrations/sharepoint
      ```
    </Accordion>
  </Tab>
</Tabs>

## Errors and edge cases

* **302 redirect**: expected for login and callback routes.
* **401/403**: token missing for refresh.
* **404**: integration artifact or project not found.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.