Crosswork Assurance API documentation - Identity & Access Management (26.11)

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.

(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.

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.