Basic Authentication in ZITADEL

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

Register the API in ZITADEL

Go to your project and click on the New button as shown below.

Give a name to your application (Test API 2 is the name given below) and select type API.

Select Basic as the authentication method and click Continue.

Now review your configuration and click Create.

You will now see the API’s Client ID and the Client Secret. Copy them and click Close.

When you click URLs on the left, you will see the relevant OIDC URLs. Note down the issuer URL, token_endpoint and introspection_endpoint.

Also note down the Resource ID of your project.

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:

Property	Description
`aud`	The audience of the token
`client_id`	The client_id of the application the token was issued to
`exp`	Time the token expires (as unix time)
`iat`	Time the token was issued at (as unix time)
`iss`	Issuer of the token
`jti`	Unique id of the token
`nbf`	Time the token must not be used before (as unix time)
`scope`	Space delimited list of scopes granted to the token
`token_type`	Type of the inspected token. Value is always Bearer
`username`	ZITADEL'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.

Register the API in ZITADEL​

Token introspection​

Introspection response​

Register the API in ZITADEL

Token introspection

Introspection response