OpenID & OAuth

Upcoming release — Zylon 1.58These 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.

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 and SharePoint.

Basic request and response

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

Google login
Microsoft login

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.

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.

Confluence login
SharePoint login

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}"

Example response

HTTP/1.1 302 Found
Location: https://auth.atlassian.com/authorize?client_id=...&redirect_uri=...

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}"

Example response

HTTP/1.1 302 Found
Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...

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

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.

Confluence instance
SharePoint instance

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}"

Example response

HTTP/1.1 302 Found
Location: https://auth.atlassian.com/authorize?client_id=...&state=conf_8a7b6c5d4e3f2a1b

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}"

Example response

HTTP/1.1 302 Found
Location: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&state=sp_1c2d3e4f5a6b7c8d

Refresh an integration token

Endpoint parameters

Type	Name	Required	Notes
Path	`integrationArtifactID`	Yes	Integration artifact to refresh.

Confluence refresh
SharePoint refresh

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}"

Example response

"ok"

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}"

Example response

"ok"

Callback endpoints

Microsoft callback
Confluence callback
SharePoint callback

Endpoint parameters

Type	Name	Required	Notes
Query	`code`	Yes	OAuth authorization code.
Query	`state`	Yes	OAuth state value returned by the provider.

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

Example response

HTTP/1.1 302 Found
Location: https://{BASE_URL}/app/login/success

Endpoint parameters

Type	Name	Required	Notes
Query	`code`	Yes	OAuth authorization code.
Query	`state`	Yes	OAuth state value returned by the provider.

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

Example response

HTTP/1.1 302 Found
Location: https://{BASE_URL}/app/integrations/confluence

Endpoint parameters

Type	Name	Required	Notes
Query	`code`	Yes	OAuth authorization code.
Query	`state`	Yes	OAuth state value returned by the provider.

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

Example response

HTTP/1.1 302 Found
Location: https://{BASE_URL}/app/integrations/sharepoint

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.

First Steps

Build with Zylon

Coding Agents

OpenID & OAuth

Basic request and response

Refresh an integration token

Callback endpoints

Errors and edge cases

​Basic request and response

​User SSO login redirects

​Integration OAuth login redirects

​Login with a specific integration instance

​Refresh an integration token

​Callback endpoints

​Errors and edge cases

Basic request and response

User SSO login redirects

Integration OAuth login redirects

Login with a specific integration instance

Refresh an integration token

Callback endpoints

Errors and edge cases