Edit

Headers

Audience: Programmer

Overview

This document details the HTTP headers used when interacting with the pyck API. These headers control authentication, tenant context, and query behavior.

Required Headers

Authorization

Authorization: Bearer <token>

  • The token can be either a JWT or a Personal Access Token (PAT)

  • Example: Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEu...

  • Missing or invalid tokens result in 403 Forbidden responses

NOTE: The Authorization header is required for all authenticated endpoints except the following GraphQL mutations/queries:

  • registerTenant

Tenant Context Headers

X-Pyck-Tenant-Id

  • Specifies one or more tenants (organizations) for the request

  • Used for both query and mutation operations

    • Example: X-Pyck-Tenant-Id: d4b5319e-1daa-57ed-9676-c6bfc717cf76

  • To provide multiple tenant IDs, you can set the header multiple times and/or add multiple tenant IDs to a single header by separating them with a comma

    • Example: X-Pyck-Tenant-Id: d4b5319e-1daa-57ed-9676-c6bfc717cf76,7cdbc30a-6f27-5aa1-bd4a-e7d5106075a5

  • You can use the special tenant ID all to select all tenants the user has access to.

    • Example: X-Pyck-Tenant-Id: all

  • For query operations, if not provided, it defaults to all.

  • For mutations (create/update/delete), you must always provide exactly one tenant ID. You cannot use the special all tenant ID for mutations.

Multi-Tenant Operations

When working with multi-tenant contexts:

  • Query operations can use X-Pyck-Tenant-Id to retrieve data from one or more tenant contexts

  • Mutation operations must use exactly one tenant in X-Pyck-Tenant-Id

  • The system validates that tenants specified in headers are accessible to the authenticated user

Setting the Tenant Context for Mutations

All mutation operations require an unambiguous tenant context. While query operations can span multiple tenants, mutations must target exactly one tenant for data integrity.

For users with access to a single tenant:

  • The tenant context is automatically inferred from the JWT when the X-Pyck-Tenant-Id header is omitted

  • This provides a convenient default for single-tenant scenarios

For users with access to multiple tenants:

  • The X-Pyck-Tenant-Id header is mandatory

  • The API will return an error if the header is missing

  • You must explicitly specify which tenant the mutation should affect

For system users and service tokens:

  • System users operate differently - they have no default tenant context by design, as they can operate across all tenant boundaries

  • When performing mutations with a system user token, you must always include the X-Pyck-Tenant-Id header to explicitly specify which tenant the mutation should affect

  • Omitting this header will result in the error message: "cannot determine mutation tenant ID"

Best practice: To avoid errors, always include X-Pyck-Tenant-Id: <tenant-uuid> in your mutation requests when using system tokens or when you have access to multiple tenants.

Additional Headers

X-Pyck-Feature

  • Used to selectively enable additional features in the API

  • Can be provided multiple times with one or more feature IDs separated by comma

The following features can be toggled on:

showdeleted

  • Controls whether deleted resources should be included in query results

  • Example: X-Pyck-Feature: showdeleted

Content-Type Headers

For API Requests

  • Required for all POST requests to the API

  • All request bodies should be valid JSON

Authentication Providers

While ZITADEL is the reference implementation for authentication in pyck, the system is designed to support other identity providers. The headers and authentication mechanisms described here are part of pyck's API contract and will remain consistent regardless of the underlying authentication provider.

Best Practices

  • Always include the Authorization header for authenticated endpoints

  • Always explicitly specify the tenant(s) to use. Use all to query all tenants.

  • Only enable the showdeleted feature when specifically needing to access deleted resources

  • Set appropriate Content-Type headers for all requests

PreviousAuthenticationNextNetworking Requirements

Last updated

Was this helpful?