https://github.com/zitadel/examples-api-access-and-token-introspection
Python examples for securing an API and invoking it as a service user
https://github.com/zitadel/examples-api-access-and-token-introspection
api-client api-rest examples jwt python
Last synced: about 2 months ago
JSON representation
Python examples for securing an API and invoking it as a service user
- Host: GitHub
- URL: https://github.com/zitadel/examples-api-access-and-token-introspection
- Owner: zitadel
- Created: 2023-03-20T12:15:17.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-07-16T09:58:37.000Z (9 months ago)
- Last Synced: 2025-10-11T03:31:48.173Z (6 months ago)
- Topics: api-client, api-rest, examples, jwt, python
- Language: Python
- Homepage: https://zitadel.com/
- Size: 12.3 MB
- Stars: 18
- Watchers: 1
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# api-access-and-token-introspection
Find a detailed explanation of the concepts covered in these examples in this [blog post](https://zitadel.com/blog/api-access-and-introspection).
## API Application:
If you have an API that behaves as an OAuth resource server that can be accessed by user-facing applications and need to validate an access token by calling the ZITADEL introspection API, you can use the following methods to register these APIs in ZITADEL:
- [JSON Web Token (JWT) Profile (Recommended)](https://zitadel.com/docs/apis/openidoauth/authn-methods#jwt-with-private-key)
- [Test JWT Profile for API Applications](https://github.com/zitadel/examples-api-access-and-token-introspection/tree/main/api-jwt)
- [Basic Authentication](https://zitadel.com/docs/apis/openidoauth/authn-methods#client-secret-basic)
- [Test Basic Authentication for API Applications](https://github.com/zitadel/examples-api-access-and-token-introspection/tree/main/api-basic-authentication)
## Service Users:
If there are client APIs or systems that need to access other protected APIs, these APIs or systems must be declared as service users. A service user is not considered an application type in ZITADEL. The following mechanisms are available for service users to obtain an access token:
- [JSON Web Token (JWT) Profile (Recommended)](https://zitadel.com/docs/guides/integrate/serviceusers)
- [Test JWT Profile for Service Users](https://github.com/zitadel/examples-api-access-and-token-introspection/tree/main/service-user-jwt)
- [Client Credentials](https://zitadel.com/docs/guides/integrate/client-credential)
- [Test Client Credentials for Serivce Users](https://github.com/zitadel/examples-api-access-and-token-introspection/tree/main/service-user-client-credentials)
- [Personal Access Tokens (PAT)](https://zitadel.com/docs/guides/integrate/pat)
- [Test Personal Access Tokens for Service Users](https://github.com/zitadel/examples-api-access-and-token-introspection/tree/main/service-user-pat)
## All Possible Combinations:
| **#** | **Grant and Token Type Used by Service User** | **How the Application API Invokes the Introspection Endpoint** |
|-------|---------------------------------------------------------------------------------------|----------------------------------------------------------------|
| 1 | Send JWT to ZITADEL to receive an opaque token or JWT and send the received token to API (JWT Profile) | JWT Profile |
| 2 | Send JWT to ZITADEL to receive an opaque token or JWT and send the received token to API (JWT Profile) | Basic Authentication |
| 3 | Send Client ID and Client Secret to ZITADEL and receive an opaque token or JWT and send the received token to API (Client Credentials) | JWT Profile |
| 4 | Send Client ID and Client Secret to ZITADEL and receive an opaque token or JWT and send the received token to API (Client Credentials) | Basic Authentication |
| 5 | Send a static access token to API (Personal Access Token) | JWT Profile |
| 6 | Send a static access token to API (Personal Access Token) | Basic Authentication |
## Prerequisites to Run the Samples:
- Clone this repository.
- Have python3 and pip3 installed in your machine.
- Install required dependencies by running `pip3 install -r requirements.txt` on your terminal.
- Create a free ZITADEL account here - https://zitadel.cloud/
- Create an instance as explained [here](https://zitadel.com/docs/guides/start/quickstart#2-create-your-first-instance).
- Create a new project in your instance by following the steps [here](https://zitadel.com/docs/guides/start/quickstart#2-create-your-first-instance).
- Make sure that you replace the values in the .env file in each project with the values you obtain from ZITADEL.