Basic Authentication in ZITADEL

import IntrospectionResponse from './_introspection-response.mdx';

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.

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

3. Select Basic as the authentication method and click Continue.

4. Now review your settings and click Create.

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

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

7. Also note down the Project 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 ${CUSTOM_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

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