API docs by Redocly

Provider Connectivity Assurance API documentation - Identity & Access Management (25.7)

Download OpenAPI specification:

Introduction

This API is documented in Open API format v2. You can download the full API spec above, and use it with compatible code generators to generate the client stubs.

Quick Setup

(Almost) every endpoint require a valid user authentication, so this is probably where you should start. Depending on the access rights associated with your account, some endpoints may not be authorized. When such restriction exists, the API documentation will outline which access rights are required to access or modify a given resource.

Authenticate with OAuth 2.0 PKCE

You can obtain an access token using the OAuth 2.0 Authorization Code flow with PKCE. This is a two-step process that requires browser interaction for the authorization step.

Prerequisites

  1. Client ID: Obtain the AnalyticsUI client ID from your IAM console. Login to your tenant with a tenant-admin role and navigate to the Applications section to find the client ID.
  2. Authority URL: The IAM authority URL for your deployment (e.g., https://auth.{deployment}.{domain}).
  3. Callback URL: A registered redirect URI for your tenant's application (e.g., https://{tenant}.{deployment}.{domain}/login).

Step 1: Generate PKCE and Security Parameters

Generate the required PKCE code verifier/challenge and recommended security parameters:

# Generate code_verifier (43-128 characters, URL-safe)
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=' | tr '/+' '_-' | cut -c1-43)

# Generate code_challenge (SHA256 hash, base64url encoded)
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr -d '=' | tr '/+' '_-')

# Generate state (to prevent CSRF attacks)
STATE=$(openssl rand -base64 16 | tr -d '=' | tr '/+' '_-')

# Generate nonce (to bind client session with id_token)
NONCE=$(openssl rand -base64 16 | tr -d '=' | tr '/+' '_-')

echo "code_verifier: $CODE_VERIFIER"
echo "code_challenge: $CODE_CHALLENGE"
echo "state: $STATE"
echo "nonce: $NONCE"

Step 2: Authorization Request (Browser)

Open this URL in a browser to authenticate and obtain an authorization code:

open "https://auth.{deployment}.{domain}/oauth/v2/authorize?client_id={clientId}&redirect_uri=https://{tenant}.{deployment}.{domain}/login&response_type=code&scope=openid%20profile%20email%20urn:zitadel:iam:org:projects:roles%20urn:zitadel:iam:org:project:id:zitadel:aud%20urn:zitadel:iam:user:metadata&code_challenge={code_challenge}&code_challenge_method=S256&state={state}&nonce={nonce}"

Note: The URL must be quoted and spaces in the scope must be URL-encoded as %20.

After authenticating, you will be redirected to your callback URL with code and state parameters (e.g., https://{tenant}.{deployment}.{domain}/login?code=ABC123...&state={state}). Verify the returned state matches your original value to prevent CSRF attacks.

Step 3: Exchange Code for Token

curl -X POST \
  https://auth.{deployment}.{domain}/oauth/v2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'client_id={clientId}' \
  -d 'code={authorization_code}' \
  -d 'redirect_uri=https://{tenant}.{deployment}.{domain}/login' \
  -d 'code_verifier={code_verifier}'

Replace {deployment}, {domain}, {clientId}, {authorization_code}, and {code_verifier} with your actual values.

Example Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 43199,
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email urn:zitadel:iam:org:projects:roles urn:zitadel:iam:org:project:id:zitadel:aud urn:zitadel:iam:user:metadata"
}

Using the Access Token

Include the access token in the Authorization header for subsequent API calls:

curl -X GET \
  https://{url}/api/v3/users \
  -H 'Authorization: Bearer {access_token}'

Using an API Client (Bruno)

You can also use an API client like Bruno to handle the OAuth 2.0 PKCE flow automatically:

  1. Create a new request in Bruno and go to the Auth tab.
  2. Select Grant Type: Authorization Code
  3. Configure the OAuth settings:
    • Callback URL: https://{tenant}.{deployment}.{domain}/login
    • Authorization URL: https://auth.{deployment}.{domain}/oauth/v2/authorize
    • Access Token URL: https://auth.{deployment}.{domain}/oauth/v2/token
    • Client ID: Your AnalyticsUI client ID
    • Scope: urn:zitadel:iam:org:projects:roles,urn:zitadel:iam:org:project:id:zitadel:aud,urn:zitadel:iam:user:metadata
  4. Enable PKCE: Check the "Use PKCE" checkbox (Bruno will generate the code verifier and challenge automatically).
  5. Token settings:
    • Add token to: Headers
    • Header Prefix: Bearer
  6. Click Get Access Token to initiate the OAuth flow. Bruno will open a browser for authentication and automatically capture the authorization code and exchange it for an access token.

Once configured, Bruno will automatically include the access token in subsequent requests and can refresh it when needed.

CertificateService

RenewCerts

query Parameters
certduration
string
format
string
Default: "der"
Enum: "der" "pem"
Request Body schema: application/octet-stream
required
string <binary>

Responses

SignCSR

Returns a signed certificate based on a client signed request provided. This API requires the tenant-admin role.

query Parameters
certduration
string

The certificate validity time (in hour)

format
string
Default: "der"
Enum: "der" "pem"

The certificate format to be returned

requestedUsername
string

User identity (email/username) to associate with the issued certificate. If omitted, defaults to the caller (X-Forwarded-User-Username). (this is required for CAS backward compatibility. This behavior will be removed when we retire CAS)

assignedRoles
Array of strings
Default: "tenant-contributor"

Roles to assign to the service account tied to the certificate signed and return by this request

Request Body schema: application/octet-stream
required

A client signed request as generated by openssl For instance: openssl req -newkey rsa:2048 -nodes -keyout client.key -out client.csr

string <binary>

Responses

Returns data of all client certs.

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "bodyFilters": { },
  • "links": {
    },
  • "data": [
    ]
}

Get cert data of certificate specified by serial number.

path Parameters
serialNum
required
integer <int64>

Unique Serial Number identifier of the Certificate to be returned

Responses

Response samples

Content type
application/vnd.api+json
{
  • "expiry": 1735689600,
  • "reason": "Unspecified",
  • "serialNum": "291606795498498048",
  • "status": "Good",
  • "tenantId": "abcd12a1-1234-12ab-123a-1abcd123a1a1",
  • "userId": "291606795498498048"
}

Revoke an existing Client Cert in Skylight AAA. Does not update Expiry.

path Parameters
serialNum
required
integer <int64>

Unique Serial Number identifier of the Certificate to be returned

Request Body schema: application/vnd.api+json
required
reason
required
string
Enum: "Unspecified" "KeyCompromise" "CACompromise" "AffiliationChanged" "Superseded" "CessationOfOperation" "CertificateHold" "RemoveFromCRL" "PrivilegeWithdrawn" "AACompromise"

Responses

Request samples

Content type
application/vnd.api+json
{
  • "reason": "Unspecified"
}

Response samples

Content type
application/vnd.api+json
{
  • "expiry": 1735689600,
  • "reason": "Unspecified",
  • "serialNum": "291606795498498048",
  • "status": "Good",
  • "tenantId": "abcd12a1-1234-12ab-123a-1abcd123a1a1",
  • "userId": "291606795498498048"
}

Certificate OCSP check request

path Parameters
ocspRequest
required
string

OCSP DER encoded request

Responses

HealthService

LivenessCheck

Responses

Response samples

Content type
application/json
"OK"

ReadinessCheck

Responses

Response samples

Content type
application/json
"OK"

IdentityProviderService

Get all external identity providers for a specified tenant

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "data": {
    }
}

Disable the external identity providers for a specified tenant and all associated users

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required

A list of external identity provider IDs to disable

required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
"Forbidden"

Add a new SAML external identity provider to the specified tenant

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema: multipart/form-data
required
name
required
string

The name of the external identity provider.

metadataUrl
string

The URL where the SAML metadata can be found. One of metadataUrl or metadataFile is required.

metadataXmlFile
string <binary>

The SAML metadata XML file. One of metadataUrl or metadataFile is required.

isDefault
boolean

Whether this SAML IdP should be set as the tenant's default IdP. Defaults to false if omitted.

Responses

Response samples

Content type
{
  • "id": "291606795498498571",
  • "isDefault": false,
  • "name": "ExampleSamlIDP",
  • "type": "IDENTITY_PROVIDER_TYPE_SAML"
}

Update the default SAML identity provider flag for the specified IdP

path Parameters
id
required
string

The ID of the SAML identity provider to update

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema: multipart/form-data
isDefault
boolean

Whether this SAML IdP should be the tenant's default IdP. Only one default IdP is allowed per tenant.

Responses

Response samples

Content type
{
  • "id": "291606795498498571",
  • "isDefault": false,
  • "name": "ExampleSamlIDP",
  • "type": "IDENTITY_PROVIDER_TYPE_SAML"
}

OnboardingService

Retrieves the generic identifying information for a customer.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

RoleService

List custom Roles

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

NameFilter
string

Regex for custom role name filter

FeatureRolesFilter
string

Feature role for custom role filter

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "bodyFilters": { },
  • "links": {
    },
  • "data": {
    },
  • "meta": {
    }
}

Create a custom Role

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": {
    }
}

Retrieve a single custom Role by its ID

path Parameters
id
required
string

The ID of the custom role to be returned

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update a custom Role

path Parameters
id
required
string

The ID of the custom role to be updated

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": {
    }
}

Delete a single custom Role by its ID

path Parameters
id
required
string

The ID of the custom role to be returned

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
application/vnd.api+json
"Custom role successfully deleted"

Retrieve list of feature roles available for custom roles

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

ServiceAccountService

Create a service account and return the associated personal access token (PAT)

query Parameters
withPAT
boolean

If set to true, a valid Personal Access Token for the service account is created and returned as well. Requires expirationDate

roles
Array of strings
Default: "tenant-admin"

The roles to assign to the service account. If not set, the default role 'tenant-admin' is assigned. Roles cannot exceed that of the caller

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema: application/json
required
accessTokenType
required
string
Default: "Bearer"
Enum: "Bearer" "Jwt"
description
string <= 400 characters
expirationDate
string <date-time>
name
required
string <= 150 characters
roles
Array of strings

List of static roles to apply to this service account, will default to tenant-admin if none provided

username
required
string <= 150 characters

Responses

Request samples

Content type
application/json
{
  • "accessTokenType": "Bearer",
  • "description": "description for pca tenant",
  • "expirationDate": "2021-01-01T01:00:00+00:00",
  • "name": "ServiceAccount1",
  • "roles": [
    ],
  • "username": "ServiceAccount1@pca"
}

Response samples

Content type
{
  • "description": "description for service account",
  • "machineUserId": "291606795498498048",
  • "name": "ServiceAccount1",
  • "username": "ServiceAccount1@pca",
  • "pat": "string"
}

Get a service account by id

path Parameters
machineUserId
required
string

the internal machine id of the service account, self is also accepted to allow response for the authenticated machine

header Parameters
X-Forwarded-Tenant-Id
required
string
X-Forwarded-User-Id
string

Responses

Response samples

Content type
{
  • "data": {
    }
}

Delete a service account

path Parameters
machineUserId
required
string
header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
"Bad request: invalid service account ID"

Create a private key for the given service account

path Parameters
machineUserId
required
string

the internal machine id of the service account, self is also accepted to allow credential renewal for the authenticated machine

header Parameters
X-Forwarded-Tenant-Id
required
string
X-Forwarded-User-Id
string
Request Body schema: application/json
required
expirationDate
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "expirationDate": "2021-01-01T01:00:00+00:00"
}

Response samples

Content type
{
  • "expirationDate": "2021-01-01T01:00:00+00:00",
  • "key": "string",
  • "keyId": "291606795498498048",
  • "organizationId": "291606795498498048",
  • "projectId": "291606795498498048",
  • "type": "string",
  • "userId": "291606795498498048"
}

Delete a private key for the given service account

path Parameters
machineUserId
required
string

The internal machine id of the service account. Using self is also accepted to allow credential deletion for the authenticated machine.

credentialId
required
string

The credential id to delete from the service account

header Parameters
X-Forwarded-Tenant-Id
required
string
X-Forwarded-User-Id
string

Responses

Response samples

Content type
"Bad request: invalid credential ID"

Create a Personal Access Token (PAT) for the given service account

path Parameters
machineUserId
required
string

the internal machine id of the service account, self is also accepted to allow credential renewal for the authenticated machine

header Parameters
X-Forwarded-Tenant-Id
required
string
X-Forwarded-User-Id
string
Request Body schema: application/json
required
expirationDate
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "expirationDate": "2021-01-01T01:00:00+00:00"
}

Response samples

Content type
{
  • "credentialId": "291606795498498048",
  • "expirationDate": "2021-01-01T01:00:00+00:00",
  • "machineUserId": "291606795498498048",
  • "pat": "ZXlKaGJHY2lPaUpTVXpJMU5pSXNJblI1Y0NJNklr..."
}

Delete a Personal Access Token (PAT) for the given service account

path Parameters
machineUserId
required
string

The internal machine id of the service account. Using self is also accepted to allow credential deletion for the authenticated machine.

credentialId
required
string

The credential id to delete from the service account

header Parameters
X-Forwarded-Tenant-Id
required
string
X-Forwarded-User-Id
string

Responses

Response samples

Content type
"Bad request: invalid credential ID"

Search Personal Access Tokens (PATs) for the given service account

path Parameters
machineUserId
required
string

The internal machine id of the service account. Using self is also accepted to allow listing PATs for the authenticated machine.

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

header Parameters
X-Forwarded-Tenant-Id
required
string
X-Forwarded-User-Id
string

Responses

Response samples

Content type
{
  • "bodyFilters": { },
  • "links": {
    },
  • "data": [
    ],
  • "meta": {
    }
}

Search for a service account based on given criteria

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "bodyFilters": { },
  • "links": {
    },
  • "data": [
    ]
}

SessionService

Validate a cert authorization, does not perform authentication. Sets headers for proxy requests to have access to the Tenant Id.

Responses

Validate an active Skylight Session. Sets headers for proxy requests to have access to user data.

Responses

Validate a PAT or access_token. Sets headers for proxy requests to have access to the Tenant Id.

Responses

TenantService

Check if SMTP is enabled

Returns the status of the SMTP configuration to indicate whether it is enabled on the deployment.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "smtpEnabled": true
}

Accept terms for provided user

Will update metadata for the provided user to designate accepted terms and conditions

header Parameters
X-Forwarded-Tenant-Id
required
string
X-Forwarded-User-Id
required
string

Responses

Adds tenant identifying information which is retrieved in the 'onboarding/tenant-info' call. Operation is only available to Skylight Administrators.

Request Body schema: application/vnd.api+json
required
object (TenantInfo)

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Deletes tenant identifying information. Operation is only available to Skylight Administrators.

path Parameters
subdomain
required
string

Unique identifier of the Subdomain to delete the tenant mapping

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

UsergroupService

Create a user group

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": {
    }
}

Get user group by ID

path Parameters
id
required
string

The ID of the user group to be returned

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "data": {
    }
}

Update a user group

path Parameters
id
required
string

The ID of the user group to be updated

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": {
    }
}

Delete user group with ID

path Parameters
id
required
string

The ID of the user group to be deleted

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
"Forbidden"

Get all users from a specified user group

path Parameters
id
required
string

The ID of the user group

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "data": [
    ],
  • "meta": {
    }
}

Add a user to the user group

path Parameters
id
required
string

The ID of the user group

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
Array of objects

Responses

Request samples

Content type
{
  • "data": [
    ]
}

Response samples

Content type
{
  • "errors": [
    ]
}

Remove a user from a specified user group

path Parameters
id
required
string

The ID of the user group

userId
required
string

The ID of the user

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
"Forbidden"

Search user groups

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": [
    ],
  • "meta": {
    }
}

UserService

Create a user

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": {
    }
}

Get user by ID

path Parameters
id
required
string

The ID of the user

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "data": {
    }
}

Update an existing user

path Parameters
id
required
string

The ID of the user

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": {
    }
}

Delete user with ID

path Parameters
id
required
string

The ID of the user

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
"Forbidden"

Get all user groups the user belongs to

path Parameters
id
required
string

The ID of the user

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "data": [
    ],
  • "meta": {
    }
}

Get all external identity providers for a specified user

path Parameters
id
required
string

The ID of the user

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "data": {
    }
}

Update which external identity providers are associated to the specified user. This request can be used to add or remove associations in bulk.

path Parameters
id
required
string

The ID of the user

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required

A list of external identity provider IDs to associate to the specified user

required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": {
    }
}

Get all roles for a specified user

path Parameters
id
required
string

The ID of the user

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
{
  • "data": {
    },
  • "meta": {
    }
}

Add roles to the specified user

path Parameters
id
required
string

The ID of the user

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
Array of objects

Responses

Request samples

Content type
{
  • "data": [
    ]
}

Response samples

Content type
{
  • "errors": [
    ]
}

Remove a target role from the user with ID

path Parameters
id
required
string

The ID of the user

roleName
required
string

The name of the role

header Parameters
X-Forwarded-Tenant-Id
required
string

Responses

Response samples

Content type
"Forbidden"

Search for user based on given criteria

query Parameters
page
integer >= 1

The page index of the returned results.

pageSize
integer >= 1

The maximum number of results to return on a page.

header Parameters
X-Forwarded-Tenant-Id
required
string
Request Body schema:
required
required
object

Responses

Request samples

Content type
{
  • "data": {
    }
}

Response samples

Content type
{
  • "data": [
    ],
  • "meta": {
    }
}