Authentication

GraphQL API Authentication

Overview

All GraphQL API requests to pyck must be authenticated. This document explains how to authenticate your API requests.

Authentication Methods

The pyck GraphQL API supports two primary authentication methods:

1. JWT Token Authentication

JWT (JSON Web Token) authentication is the most common method and involves including a valid JWT token in the Authorization header of your requests.

Authorization: Bearer <your_jwt_token>

JWT tokens are typically obtained through the ZITADEL authentication flow. Once you have a token, include it in all your API requests.

2. Personal Access Token (PAT)

For system integrations and automation, you can use a Personal Access Token:

Authorization: Bearer <your_personal_access_token>

PATs are long-lived tokens that can be created through the pyck administration interface.

Example Authentication Flow

1. Obtain a JWT Token

Authenticate with ZITADEL to obtain a JWT token. This typically involves redirecting the user to the ZITADEL login page and handling the callback with the token.

2. Make Authenticated Requests

Once you have a token, include it in your GraphQL requests:

// Example with fetch API
const response = await fetch('https://api.pyck.ai/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    query: `
      query {
        me {
          id
          name
          email
        }
      }
    `
  })
});

3. Handle Token Expiration

JWT tokens expire after a certain period. When a token expires, you'll receive a 401 Unauthorized response. You should:

1. Detect the 401 response

2. Request a new token using the refresh token flow

3. Retry the original request with the new token

Testing Authentication

You can test your authentication by querying the me endpoint, which returns information about the authenticated user:

query {
  me {
    id
    name
    email
  }
}

If authentication is successful, you'll receive information about your user. If not, you'll receive an error message.