> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/development/headers.md). # 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 ``` * 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 ``` 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: ` in your mutation requests when using system tokens or when you have access to multiple tenants. ## Additional Headers ### X-Pyck-Feature ``` 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` ## Response Headers ### X-Request-ID ``` X-Request-ID: ``` * Automatically included in all HTTP responses from the pyck API * Contains a unique UUID v7 identifier generated by the server for each request * Used for request tracing, debugging, and support purposes * Example: `X-Request-ID: 01010101-0202-7303-8404-050505050505` **Use cases:** * **Debugging**: Include this ID when reporting issues to help support teams locate specific requests in logs * **Request tracing**: Track a request's flow through the system across multiple services * **Correlation**: The same request ID appears in server logs, making it easier to correlate API requests with backend operations **Note:** The request ID is always server-generated. Any client-supplied `X-Request-ID` header in the request will be ignored. ## Content-Type Headers ### For API Requests ``` Content-Type: application/json; charset=UTF-8 ``` * 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.pyck.cloud/development/headers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.