Zitadel API

Overview

The Zitadel API Edge Function provides comprehensive integration with Zitadel identity provider, enabling OIDC authentication, user synchronization, group mapping, and role-based access control. Endpoint: /functions/v1/zitadel-api Authentication: Requires Supabase authorization header for most actions

Actions

Test Connection

Tests connectivity to a Zitadel instance and validates API credentials. Action: test-connection

issuerUrl

string

required

Zitadel issuer URL (e.g., https://gate.kappa4.com)

apiToken

string

Zitadel Management API token for testing group/user access

success

boolean

Indicates if connection was successful

apiConnected

boolean

Whether API token is valid and working

groupCount

number

Number of groups/roles discovered

Example Request

curl -X POST 'https://your-project.supabase.co/functions/v1/zitadel-api?action=test-connection' \
  -H 'Content-Type: application/json' \
  -d '{
    "issuerUrl": "https://gate.kappa4.com",
    "apiToken": "your-api-token"
  }'

List Groups

Retrieve and sync Zitadel project roles/groups with local database. Action: list-groups or sync-groups

configId

string

required

Zitadel configuration ID from zitadel_configurations table

projectId

string

Optional Zitadel project ID to scope roles

zitadelGroups

array

Array of groups/roles from Zitadel

Show properties

string

Role key

name

string

Role name

displayName

string

Display name

mappings

array

Local group mappings

newGroupsAdded

number

Count of new groups discovered and added

rolesSource

string

Source of roles: project_roles, user_grants, or org_members

Example Request

curl -X POST 'https://your-project.supabase.co/functions/v1/zitadel-api?action=sync-groups' \
  -H 'Authorization: Bearer YOUR_SUPABASE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "configId": "uuid-of-config",
    "projectId": "123456789"
  }'

List Project Users

Retrieve users with grants/roles on a specific Zitadel project. Action: list-project-users

configId

string

required

Zitadel configuration ID

projectId

string

Zitadel project ID (uses config default if not provided)

users

array

Array of users with project access

Show ZitadelUser properties

string

Zitadel user ID

userName

string

Username

string

Email address

displayName

string

Full name

groups

string[]

Assigned roles

grantId

string

Grant ID

projectId

string

Project ID

orgId

string

Organization ID

source

string

Data source: grants, project_members, or org_users

Search Users

Search for users in the Zitadel organization. Action: search-users

configId

string

required

Zitadel configuration ID

query

string

Search query (searches username, case-insensitive)

users

ZitadelUser[]

Matching users

Get User Groups

Retrieve groups/roles for a specific user. Action: get-user-groups

configId

string

required

Zitadel configuration ID

userId

string

required

Zitadel user ID

groups

string[]

Array of role keys assigned to user

SSO Callback

Handles OIDC callback after user authentication, creates/updates local user. Action: sso-callback

configId

string

required

Zitadel configuration ID

code

string

required

Authorization code from OAuth flow

codeVerifier

string

PKCE code verifier for authorization code flow

success

boolean

Whether authentication succeeded

string

User’s email address

tempPassword

string

Temporary password for Supabase sign-in

userInfo

object

User information from Zitadel

Show properties

sub

string

Zitadel user ID

name

string

Display name

string

groups

string[]

User groups

roles

string[]

User roles

orgId

string

Organization ID

orgName

string

Organization name

Get Auth URL

Generates Zitadel authorization URL for OIDC login flow. Action: get-auth-url

configId

string

required

Zitadel configuration ID

state

string

required

OAuth state parameter

codeVerifier

string

SHA-256 hashed code challenge for PKCE

authUrl

string

Complete authorization URL to redirect user to

state

string

State value for verification

nonce

string

Nonce for ID token validation

TypeScript Interfaces

TypeScript

interface ZitadelConfig {
  id: string
  issuer_url: string
  client_id: string
  client_secret: string
  redirect_uri: string
  scopes: string[]
  api_token: string
  project_id?: string
  sync_groups: boolean
}

interface ZitadelGroup {
  id: string
  name: string
  displayName: string
}

interface ZitadelUser {
  id: string
  userName: string
  email: string
  displayName: string
  groups: string[]
  grantId?: string
  projectId?: string
  projectName?: string
  orgId?: string
  orgName?: string
}

Role Mapping

The function automatically maps Zitadel roles to local roles:

Zitadel Role	Local Role
`global_admin`, `admin`, `administrator`	`global_admin`
`org_admin`, `org_manager`	`org_admin`
`support`, `helpdesk`	`support`
`user`, `member`, `viewer`	`user`

Error Handling

error

string

Error message if request fails

Common errors:

Configuration not found - Invalid configId
API token not configured - Missing API token for action
OIDC Discovery failed - Cannot reach Zitadel instance
Failed to fetch user grants - Insufficient permissions

zitadel_configurations - Zitadel instance configurations
zitadel_group_mappings - Maps Zitadel roles to local groups
user_zitadel_identities - Links users to Zitadel identities

Edge Functions

Database Schema

Overview

Actions

Test Connection

List Groups

List Project Users

Search Users

Get User Groups

SSO Callback

Get Auth URL

TypeScript Interfaces

Role Mapping

Error Handling

Build docs developers (and LLMs) love

Edge Functions

Database Schema

​Overview

​Actions

​Test Connection

​List Groups

​List Project Users

​Search Users

​Get User Groups

​SSO Callback

​Get Auth URL

​TypeScript Interfaces

​Role Mapping

​Error Handling

​Related Tables

Build docs developers (and LLMs) love

Overview

Actions

Test Connection

List Groups

List Project Users

Search Users

Get User Groups

SSO Callback

Get Auth URL

TypeScript Interfaces

Role Mapping

Error Handling

Related Tables