Skip to main content

Access ZITADEL APIs

DescriptionLearn how to authorize Service Users to access ZITADEL APIs.
Learning OutcomesIn this module you will:
  • Grant a Service User for ZITADEL
  • Authorize a Service User with JWT signed with your private key
Prerequisites

ZITADEL Managers

ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers.

  • IAM Managers: This is the highest level. Users with IAM Manager roles are able to manage the whole instance.
  • Org Managers: Managers in the Organization Level are able to manage everything within the granted Organization.
  • Project Mangers: In this level the user is able to manage a project.
  • Project Grant Manager: The project grant manager is for projects, which are granted of another organization.

On each level we have some different Roles. Here you can find more about the different roles: ZITADEL Manager Roles

Exercise: Add ORG_OWNER to Service User

Make sure you have a Service User with a Key. (For more detailed informations about creating a service user go to Service User)

  1. Navigate to Organization Detail
  2. Click the + button in the right part of console, in the managers part of details
  3. Search the user and select it
  4. Choose the role ORG_OWNER

Add Org Manager

Authenticating a service user

In ZITADEL we use the private_jwt (“JWT bearer token with private key”, RFC7523) authorization grant for this non-interactive authentication. This is already described in the Service User, so make sure you follow this guide.

Request an OAuth token, with audience for ZITADEL

With the encoded JWT 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 custom scope for the audience. More about Custom Scopes

Use the scope urn:zitadel:iam:org:project:id:{projectid}:aud to include the project id in your audience

The scope for zitadel.ch is: urn:zitadel:iam:org:project:id:69234237810729019:aud

curl --request POST \
--url {your_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 email urn:zitadel:iam:org:project:id:69234237810729019:aud' \
--data assertion=eyJ0eXAiOiJKV1QiL...
  • 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. For this example, please include profile and email
  • 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
}

With this token you are allowed to access the ZITADEL APIs .

Knowledge Check

  • Managers are used for all users to get authorizations for all projects?
    • yes
    • no
  • You need the ZITADEL Project Id in your audience and can access this with a custom scope?
    • yes
    • no
Solutions
  • Managers are used for all users to get authorizations for all projects?
    • yes
    • no (Managers are only used to grant users for ZITADEL)
  • You need the ZITADEL Project Id in your audience and can access this with a custom scope?
    • yes
    • no

Summary

  • Grant a user for ZITADEL
  • Because there is no interactive logon, you need to use a JWT signed with your private key to authorize the user
  • With a custom scope (urn:zitadel:iam:org:project:id:{projectid}:aud) you can access ZITADEL APIs

Where to go from here: