Personal Access Tokens

Non-interactive authentication for CI/CD pipelines and automation

Personal Access Tokens (PATs) let you authenticate with Pipecat Cloud without an interactive browser login. They’re designed for headless environments like CI/CD pipelines, Docker containers, and automation scripts.

When to use PATs

Scenario	Recommended auth
Local development	OAuth via pipecat cloud auth login
CI/CD pipelines	PAT via PIPECAT_TOKEN env var
Docker / remote servers	PAT via PIPECAT_TOKEN or use-pat
Shared automation scripts	PAT via PIPECAT_TOKEN env var

PATs are different from API keys. API keys authenticate REST API requests to start agent sessions or manage resources. PATs authenticate you (or a service account) to the CLI — they are not intended for direct API calls.

Creating a PAT

Generate a PAT from the Pipecat Cloud dashboard:

1. Open account settings

   Navigate to Account Settings → Personal Access Tokens in the dashboard.

2. Create a new token

   Click Create Token, give it a descriptive name (e.g. github-actions-deploy), and copy the token value. PATs start with pcc_pat_.

3. Store it securely

   Save the token in your CI/CD platform’s secret store (e.g. GitHub Actions secrets, GitLab CI variables). You won’t be able to view the token again after leaving the page.

Using a PAT

Environment variable (recommended)

Set PIPECAT_TOKEN before running any CLI command. The CLI will authenticate using the token and automatically resolve your default organization.

export PIPECAT_TOKEN="pcc_pat_..."
pipecat cloud auth whoami
pipecat cloud agent list

You can also set it inline for a single command:

PIPECAT_TOKEN="pcc_pat_..." pipecat cloud deploy my-agent

To target a specific organization, set PIPECAT_ORG as well:

export PIPECAT_TOKEN="pcc_pat_..."
export PIPECAT_ORG="my-team-org"
pipecat cloud agent list

Storing a PAT locally

If you prefer not to set an environment variable each time, you can store a PAT in your local config file:

pipecat cloud auth use-pat pcc_pat_...

This validates the token against the API and writes it to ~/.config/pipecatcloud/pipecatcloud.toml. All subsequent commands will use it automatically, just like after auth login.

CI/CD examples

GitHub Actions

Add your PAT as a repository secret named PIPECAT_TOKEN, then reference it in your workflow:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      PIPECAT_TOKEN: ${{ secrets.PIPECAT_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5

      - name: Install CLI
        run: uv tool install "pipecat-ai[cli]" --with pipecatcloud

      - name: Deploy
        run: pipecat cloud deploy my-agent --yes

For deployments specifically, the Deploy to Pipecat Cloud GitHub Action uses an API key instead. PATs are useful when you need to run arbitrary CLI commands in CI (e.g. managing secrets, listing agents, or scripting multi-step workflows).

GitLab CI

Add PIPECAT_TOKEN as a CI/CD variable (Settings → CI/CD → Variables, masked):

deploy:
  image: python:3.12
  script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - source $HOME/.local/bin/env
    - uv tool install "pipecat-ai[cli]" --with pipecatcloud
    - pipecat cloud deploy my-agent --yes

GitLab automatically exposes CI/CD variables as environment variables, so the CLI picks up PIPECAT_TOKEN without additional configuration.

Security considerations

• Treat PATs like passwords. Anyone with your token can act as you.
• Use your CI platform’s secret store. Never commit tokens to source control.
• Scope tokens to purpose. Create separate PATs for different pipelines so you can revoke them independently.
• Rotate periodically. Delete old tokens from the dashboard and generate new ones.

Next steps

CI with GitHub Actions

Automate deploys with the official GitHub Action.

Accounts and Organizations

Learn about organizations, API keys, and access control.