Skip to main content

Basic Authentication in ZITADEL

This is a guide on how to secure your API using Basic Authentication.

Register the API in ZITADEL​

  1. Go to your project and click on the New button as shown below.
Register the API
  1. Give a name to your application (Test API 2 is the name given below) and select type API.
Register the API
  1. Select Basic as the authentication method and click Continue.
Register the API
  1. Now review your configuration and click Create.
Register the API
  1. You will now see the API’s Client ID and the Client Secret. Copy them and click Close.
Register the API
  1. When you click URLs on the left, you will see the relevant OIDC URLs. Note down the issuer URL, token_endpoint and introspection_endpoint.
Register the API
  1. Also note down the Resource ID of your project.
Register the API

Token introspection​

With Basic Authentication, you will receive a Client ID and Client Secret for your API. Send your client_id and client_secret as a Basic Auth Header in the following format:

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

The request from the API to the introspection endpoint should be in the following format:

curl --request POST \
--url {your_domain}/oauth/v2/introspect \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {your_basic_auth_header}' \
--data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...

Here's an example of how this is done in Python code:

def introspect_token(self, token_string):
url = ZITADEL_INTROSPECTION_URL
data = {'token': token_string, 'token_type_hint': 'access_token', 'scope': 'openid'}
auth = HTTPBasicAuth(API_CLIENT_ID, API_CLIENT_SECRET)
resp = requests.post(url, data=data, auth=auth)
resp.raise_for_status()
return resp.json()

Introspection response​

Upon successful introspection, regardless of the token type or introspection method, a response with the boolean active is returned, indicating if the provided token is active and if the requesting client is part of the token audience. If active is true, further information will be provided:

PropertyDescription
audThe audience of the token
client_idThe client_id of the application the token was issued to
expTime the token expires (as unix time)
iatTime the token was issued at (as unix time)
issIssuer of the token
jtiUnique id of the token
nbfTime the token must not be used before (as unix time)
scopeSpace delimited list of scopes granted to the token
token_typeType of the inspected token. Value is always Bearer
usernameZITADEL's login name of the user. Consists of username@primarydomain

Depending on the granted scopes, additional information about the authorized user is provided.

If the authorization fails, an HTTP 401 with invalid_client will be returned.

In summary, the introspection endpoint plays a crucial role in validating access tokens, either opaque or JWT, ensuring that they are not revoked.

Follow this tutorial to learn how to register an API application using Basic Auth with ZITADEL and test it.