Authentication

Audience: Programmer

Overview

pyck uses ZITADEL for authentication and authorization. This document explains how to implement authentication when integrating with the pyck backend API.

Authentication Flow

1. Authentication is handled via JWT tokens or Personal Access Tokens (PATs)

2. The authentication middleware validates these tokens against ZITADEL

3. User information, including roles and tenant information, is extracted and added to the request context

Authentication Methods

JWT Authentication

• Standard OpenID Connect flow using JWT tokens

• Tokens are validated against ZITADEL's JWKS endpoint

• Token validation includes signature verification and claims validation

Personal Access Token (PAT) Authentication

• Alternative authentication method using long-lived tokens

• PATs are introspected against ZITADEL's token introspection endpoint

• Results are cached to improve performance

Authorization

Roles and Permissions

The backend supports the following roles with increasing privilege levels:

• Reader (1000): Read-only access

• Writer (1001): Read and write access

• Admin (1002): Administrative access

• System (1003): System-level access

Tenant Isolation

• Users are associated with a tenant (organization)

• Tenant ID can be specified via HTTP headers during authentication

• Authentication ensures users can only access resources within their tenant

Implementation Details

Authentication Header

• All authenticated requests require: Authorization: Bearer <token>

• Where <token> is either a valid JWT or PAT

Error Handling

• Authentication errors return HTTP 403 Forbidden status codes

• Common errors include expired tokens, invalid signatures, or insufficient permissions

Unauthenticated Endpoints

Certain endpoints don't require authentication:

• Health check endpoints (/health)

• Metrics endpoints (/metrics)

• Webhook endpoints (paths containing /webhook/)

• Company registration GraphQL mutation

• Tenant registration GraphQL mutation (registerTenant)

Development Guide

When developing against the pyck API, you'll need to:

1. Obtain a valid token from ZITADEL

2. Include this token in the Authorization header of all API requests

3. Implement token refresh logic when tokens expire

4. Handle authentication errors appropriately in your client application

Testing Authentication

For testing purposes, you can:

1. Use the ZITADEL developer console to generate test tokens

2. Verify token validity using the introspection endpoint

3. Test different roles to ensure proper authorization behavior

Tenant Registration Email Behavior

When using the registerTenant mutation, the system allows re-use of the same admin email address across multiple tenant registrations. Each tenant receives a unique tenant-specific primary email (e.g., [email protected], [email protected]), with the original email added as an alias.

Important: Cross-tenant authorization is not supported. A user created for one tenant cannot access another tenant's resources, even if they share the same email alias.

Recommendation: Use unique email addresses for each tenant registration to avoid confusion and ensure clear account separation.

For detailed information, see the registerTenant mutation documentation.