diff --git a/cli/cloud/auth.mdx b/cli/cloud/auth.mdx index ee9bc39e2..3a4d3d160 100644 --- a/cli/cloud/auth.mdx +++ b/cli/cloud/auth.mdx @@ -45,9 +45,31 @@ Signs out of the current Pipecat Cloud account by removing the access token from pipecat cloud auth logout ``` +## use-pat + +Authenticates with a [Personal Access Token](/deployment/pipecat-cloud/guides/personal-access-tokens) instead of interactive OAuth login. Validates the token against the API and stores it in your local config file. + +**Usage:** + +```shell +pipecat cloud auth use-pat +``` + +**Arguments:** + + + Personal Access Token (must start with `pcc_pat_`). + + + + You can also set the `PIPECAT_TOKEN` environment variable instead of storing + the token locally. See the [PAT guide](/deployment/pipecat-cloud/guides/personal-access-tokens) + for details. + + ## whoami -Displays information about the currently authenticated user, including user ID, active organization, and Daily API key. +Displays information about the currently authenticated user, including user ID, active organization, auth method, and Daily API key. **Usage:** diff --git a/deployment/pipecat-cloud/guides/personal-access-tokens.mdx b/deployment/pipecat-cloud/guides/personal-access-tokens.mdx new file mode 100644 index 000000000..c8c03a5d9 --- /dev/null +++ b/deployment/pipecat-cloud/guides/personal-access-tokens.mdx @@ -0,0 +1,147 @@ +--- +title: "Personal Access Tokens" +description: "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](https://pipecat.daily.co/): + + + + Navigate to **Account Settings → [Personal Access + Tokens](https://pipecat.daily.co/account/tokens)** in the dashboard. + + + Click **Create Token**, give it a descriptive name (e.g. + `github-actions-deploy`), and copy the token value. PATs start with + `pcc_pat_`. + + + 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. + +```shell +export PIPECAT_TOKEN="pcc_pat_..." +pipecat cloud auth whoami +pipecat cloud agent list +``` + +You can also set it inline for a single command: + +```shell +PIPECAT_TOKEN="pcc_pat_..." pipecat cloud deploy my-agent +``` + +To target a specific organization, set `PIPECAT_ORG` as well: + +```shell +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: + +```shell +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: + +```yml +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](./ci-with-github-actions) 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): + +```yml +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 + + + + Automate deploys with the official GitHub Action. + + + Learn about organizations, API keys, and access control. + + diff --git a/docs.json b/docs.json index 09399ee2a..2f04d65ba 100644 --- a/docs.json +++ b/docs.json @@ -615,6 +615,7 @@ ] }, "deployment/pipecat-cloud/guides/ci-with-github-actions", + "deployment/pipecat-cloud/guides/personal-access-tokens", "deployment/pipecat-cloud/guides/daily-webrtc", "deployment/pipecat-cloud/guides/krisp-viva", {