Personal Access Token Auth for Service Accounts

A Personal Access Token (PAT) is a ready-to-use token that can be used as an Authorization header. At the moment ZITADEL only allows PATs for service accounts.

It is an alternative to the private key JWT and client credentials. Read more about the different authentication methods for service accounts.

Create a Service Account with a PAT

1. Navigate to Service Accounts
2. Click on New
3. Enter a username and a display name
4. Click on the Personal Access Token menu point in the detail of your user
5. Click on New
6. You can either set an expiration date or leave it empty if you don't want it to expire
7. Copy the token from the dialog (You will not see this again)

Grant role for ZITADEL

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)

Accessing ZITADEL APIs

You might want to access ZITADEL APIs to manage resources, such as users, or to validate tokens sent to your backend service. Follow our guides on how to access ZITADEL API to use the ZITADEL APIs with your service account.

Token introspection

Your API endpoint might receive tokens from users and need to validate the token with ZITADEL. In this case your API needs to authenticate with ZITADEL and then do token introspection. Follow our guide on token introspection with private key JWT to learn more.

Call ZITADEL API with PAT

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}'

Client application authentication

The above steps demonstrate service account authentication. If your application also needs to authenticate itself, you can utilize Client Credentials Grant. Refer to ZITADEL documentation for details on this alternative method.

Security considerations

• Store private keys securely: Never share or embed the private key in your code or application. Consider using secure key management solutions.
• Set appropriate JWT expiration times: Limit the validity period of tokens to minimize the impact of potential compromise.
• Implement proper error handling: Handle situations where JWT verification fails or tokens are expired.

By following these steps and adhering to security best practices, you can effectively secure service account and client application communication within ZITADEL using private key JWT authentication.