Skip to main content
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

ScenarioRecommended auth
Local developmentOAuth via pipecat cloud auth login
CI/CD pipelinesPAT via PIPECAT_TOKEN env var
Docker / remote serversPAT via PIPECAT_TOKEN or use-pat
Shared automation scriptsPAT 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

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 CLI
        run: pip install 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:
    - pip install 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.