Access ZITADEL APIs

This guide explains what ZITADEL APIs are and how to access ZITADEL APIs using a service account to manage all types of resources and settings.

What are the ZITADEL APIs

ZITADEL exposes a variety of APIs that allow you to interact with its functionalities programmatically. These APIs are offered through different protocols, including gRPC and REST. Additionally, ZITADEL provides SDKs for popular languages and frameworks to simplify integration.

Here's a breakdown of some key points about ZITADEL APIs:

• Auth API: Used by authenticated users for tasks related to their accounts.
• Management API: Used by organization administrators for administrative tasks.
• Admin API: Used for administrative functions on the ZITADEL instance itself (may require separate user setup).
• System API: For ZITADEL self-hosted deployments only, providing superordinate control (requires specific settings).

For further details and in-depth exploration, you can refer to the ZITADEL API documentation.

How to access ZITADEL APIs

Accessing ZITADEL APIs, except for the Auth API and the System API, requires these basic steps:

1. Create a service account: A service account is a special type of account used to grant programmatic access to ZITADEL's functionalities. Unlike regular users who log in with a username and password, service accounts rely on a more secure mechanism involving digital keys and tokens.
2. Give permission to access ZITADEL APIs: Assign a Administrator role to the service account, giving it permission to make changes to certain resources in ZITADEL.
3. Authenticate the service account: Like users, service accounts must authenticate and request an OAuth token with the scope urn:zitadel:iam:org:project:id:zitadel:aud to access ZITADEL APIs. Service accounts can be authenticated using private key JWT, client credentials, or personal access tokens.
4. Access ZITADEL APIs with the token: The OAuth token must be included in the Authorization Header of calls to ZITADEL APIs.

Accessing Auth API

The Auth API can be used for all operations on the requesting user, meaning the user id in the sub claim of the used token. Using this API doesn't require a service account to be authenticated. Instead, you call the Auth API with the token of the user.

Reference documentation for authentication API

Accessing System API

With the System API developers can manage different ZITADEL instances. The System API can't be accessed by service accounts and requires special settings and authentication that can be found in our guide to access ZITADEL's System API.

Reference documentation for system API

1. Create a service account

First, you need to create a new service account through the management console or ZITADEL APIs.

Via Management Console:

1. In an organization, navigate to Users > Service Accounts
2. Click on New
3. Enter a username and a display name
4. Click on Create

Via APIs23: * Create User (Machine)

2. Grant an Administrator Role to the Service Account

ZITADEL Administrators are users who have permission to manage ZITADEL itself. There are different levels of administrators.

• IAM Administrators: This is the highest level. Users with IAM Administrator roles are able to manage the whole instance.
• Organization Administrators: Administrators at the Organization Level are able to manage everything within the granted Organization.
• Project Administrators: At this level, the user is able to manage a project.
• Project Grant Administrators: A project grant administrator manages projects which are granted by another organization.

There are different roles on each level. You can find more about the different roles here: ZITADEL Administrator Roles

To be able to access the ZITADEL APIs, your service account needs permissions to ZITADEL.

1. Go to the detail page of your organization
2. Click in the top right corner the "+" button
3. Search for your service account
4. Give the user the role you need — for example, we choose Org Owner (More about ZITADEL Permissions)

3. Authenticate service account and request token

Service accounts can be authenticated using private key JWT, client credentials, or personal access tokens. The service account authentication can be used to make machine-to-machine requests to any Resource Server (eg, a backend service / API) by requesting a token from the Authorization Server (ZITADEL) and sending the short-lived token (access token) in the Header of requests.

This guide covers a specific case of service account authentication when requesting access to the ZITADEL APIs. While PAT can be used directly to access the ZITADEL APIS, the more secure authentication methods private key JWT and client credentials must include the reserved scope urn:zitadel:iam:org:project:id:zitadel:aud when requesting an access from the token endpoint. This scope will add the ZITADEL APIs to the audience of the access token. ZITADEL APIs will check if they are in the audience of the access token and reject the token in case they are not in the audience.

The following sections will explain the more specific authentication to access the ZITADEL APIs.

Authenticate with private key JWT

Follow the steps in this guide to generate a key file and create a JWT and sign with private key.

With the encoded JWT (assertion) from the prior step, you will need to craft a POST request to ZITADEL's token endpoint.

To access the ZITADEL APIs, you need the ZITADEL Project ID in the audience of your token. This is possible by sending a reserved scope for the audience. Use the scope urn:zitadel:iam:org:project:id:zitadel:aud to include the ZITADEL project id in your audience

A sample request will look like this

curl --request POST \
  --url ${CUSTOM_DOMAIN}/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data scope='openid profile urn:zitadel:iam:org:project:id:zitadel:aud' \
  --data assertion=eyJ0eXAiOiJKV1QiL...

where

• grant_type must be set to urn:ietf:params:oauth:grant-type:jwt-bearer
• scope should contain any Scopes you want to include, but must include openid and urn:zitadel:iam:org:project:id:zitadel:aud to access the ZITADEL APIs. For this example include profile.
• assertion is the encoded value of the JWT that was signed with your private key from the prior step

You should receive a successful response with access_token, token_type and time to expiry in seconds as expires_in.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
  "token_type": "Bearer",
  "expires_in": 43199
}

Use the access_token in the Authorization header to make requests to the ZITADEL APIs. In the following example, we read the organization of the service account.

curl --request GET \
  --url ${CUSTOM_DOMAIN}/management/v1/orgs/me \
  --header 'Authorization: Bearer ${TOKEN}'

Client credentials

Get the client id and client secret by

1. navigating to the service account, then
2. Open Actions in the top right corner and click on Generate Client Secret
3. Copy the ClientID and ClientSecret from the dialog

With the ClientId and ClientSecret from the prior step, you will need to craft a POST request to ZITADEL's token endpoint.

Audience scope

To access the ZITADEL APIs you need the ZITADEL Project ID in the audience of your token. This is possible by sending a reserved scope for the audience. Use the scope urn:zitadel:iam:org:project:id:zitadel:aud to include the ZITADEL project id in your audience

In this step we will authenticate a service account and receive an access_token to use against the ZITADEL API.

Basic authentication

When using client_secret_basic on the token or introspection endpoints, provide an Authorization header with a Basic auth value in the following form:

Authorization: "Basic " + base64( formUrlEncode(client_id) + ":" + formUrlEncode(client_secret) )

For example, see the client secret basic authentication method reference. We recommend using an OpenID / OAuth library that handles the encoding for you.

Post request

You will need to craft a POST request to ZITADEL's token endpoint:

curl --request POST \
  --url https://${CUSTOM_DOMAIN}/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic ${BASIC_AUTH}' \
  --data grant_type=client_credentials \
  --data scope='openid profile urn:zitadel:iam:org:project:id:zitadel:aud'

where

• grant_type should be set to client_credentials
• scope should contain any Scopes you want to include, but must include openid. For this example, please include profile and urn:zitadel:iam:org:project:id:zitadel:aud. The latter provides access to the ZITADEL API.

You should receive a successful response with access_token, token_type and time to expiry in seconds as expires_in.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
  "token_type": "Bearer",
  "expires_in": 43199
}

Because the received token includes the urn:zitadel:iam:org:project:id:zitadel:aud scope, we can send it in your requests to the ZITADEL API as the Authorization Header. In this example, we read the organization of the service account.

curl --request GET \
  --url ${CUSTOM_DOMAIN}/management/v1/orgs/me \
  --header 'Authorization: Bearer ${TOKEN}'

Personal access token (PAT)

A Personal Access Token (PAT) is a ready-to-use token that can be used as an Authorization header.

Because the PAT is a ready-to-use token, you can add it as an Authorization Header and send it in your requests to the ZITADEL API. In this example, we read the organization of the service account.

curl --request GET \
  --url ${CUSTOM_DOMAIN}/management/v1/orgs/me \
  --header 'Authorization: Bearer {PAT}'

Notes

• Example application in Go to access ZITADEL APIs
• Example application in .NET to access ZITADEL APIs
• Learn how to use the Event API to retrieve your audit trail
• Read about the different methods to authenticate service accounts