Skip to content

Commit 6882bc2

Browse files
markbackmanmarkbackman
authored
Merge pull request #695 from pipecat-ai/ms/add-pat-user-guide
docs: add Personal Access Tokens user guide
2 parents e92c38d + b9dcb0c commit 6882bc2

3 files changed

Lines changed: 171 additions & 1 deletion

File tree

‎cli/cloud/auth.mdx‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,31 @@ Signs out of the current Pipecat Cloud account by removing the access token from
4545
pipecat cloud auth logout
4646
```
4747

48+
## use-pat
49+
50+
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.
51+
52+
**Usage:**
53+
54+
```shell
55+
pipecat cloud auth use-pat <token>
56+
```
57+
58+
**Arguments:**
59+
60+
<ParamField path="token" type="string" required>
61+
Personal Access Token (must start with `pcc_pat_`).
62+
</ParamField>
63+
64+
<Tip>
65+
You can also set the `PIPECAT_TOKEN` environment variable instead of storing
66+
the token locally. See the [PAT guide](/deployment/pipecat-cloud/guides/personal-access-tokens)
67+
for details.
68+
</Tip>
69+
4870
## whoami
4971

50-
Displays information about the currently authenticated user, including user ID, active organization, and Daily API key.
72+
Displays information about the currently authenticated user, including user ID, active organization, auth method, and Daily API key.
5173

5274
**Usage:**
5375

‎deployment/pipecat-cloud/guides/personal-access-tokens.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: "Personal Access Tokens"
3+
description: "Non-interactive authentication for CI/CD pipelines and automation"
4+
---
5+
6+
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.
7+
8+
## When to use PATs
9+
10+
| Scenario | Recommended auth |
11+
| ------------------------- | ------------------------------------ |
12+
| Local development | OAuth via `pipecat cloud auth login` |
13+
| CI/CD pipelines | PAT via `PIPECAT_TOKEN` env var |
14+
| Docker / remote servers | PAT via `PIPECAT_TOKEN` or `use-pat` |
15+
| Shared automation scripts | PAT via `PIPECAT_TOKEN` env var |
16+
17+
<Note>
18+
PATs are different from **API keys**. API keys authenticate REST API requests
19+
to start agent sessions or manage resources. PATs authenticate _you_ (or a
20+
service account) to the **CLI** — they are not intended for direct API calls.
21+
</Note>
22+
23+
## Creating a PAT
24+
25+
Generate a PAT from the [Pipecat Cloud dashboard](https://pipecat.daily.co/):
26+
27+
<Steps>
28+
<Step title="Open account settings">
29+
Navigate to **Account Settings → [Personal Access
30+
Tokens](https://pipecat.daily.co/account/tokens)** in the dashboard.
31+
</Step>
32+
<Step title="Create a new token">
33+
Click **Create Token**, give it a descriptive name (e.g.
34+
`github-actions-deploy`), and copy the token value. PATs start with
35+
`pcc_pat_`.
36+
</Step>
37+
<Step title="Store it securely">
38+
Save the token in your CI/CD platform's secret store (e.g. GitHub Actions
39+
secrets, GitLab CI variables). You won't be able to view the token again
40+
after leaving the page.
41+
</Step>
42+
</Steps>
43+
44+
## Using a PAT
45+
46+
### Environment variable (recommended)
47+
48+
Set `PIPECAT_TOKEN` before running any CLI command. The CLI will authenticate using the token and automatically resolve your default organization.
49+
50+
```shell
51+
export PIPECAT_TOKEN="pcc_pat_..."
52+
pipecat cloud auth whoami
53+
pipecat cloud agent list
54+
```
55+
56+
You can also set it inline for a single command:
57+
58+
```shell
59+
PIPECAT_TOKEN="pcc_pat_..." pipecat cloud deploy my-agent
60+
```
61+
62+
To target a specific organization, set `PIPECAT_ORG` as well:
63+
64+
```shell
65+
export PIPECAT_TOKEN="pcc_pat_..."
66+
export PIPECAT_ORG="my-team-org"
67+
pipecat cloud agent list
68+
```
69+
70+
### Storing a PAT locally
71+
72+
If you prefer not to set an environment variable each time, you can store a PAT in your local config file:
73+
74+
```shell
75+
pipecat cloud auth use-pat pcc_pat_...
76+
```
77+
78+
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`.
79+
80+
## CI/CD examples
81+
82+
### GitHub Actions
83+
84+
Add your PAT as a repository secret named `PIPECAT_TOKEN`, then reference it in your workflow:
85+
86+
```yml
87+
jobs:
88+
deploy:
89+
runs-on: ubuntu-latest
90+
env:
91+
PIPECAT_TOKEN: ${{ secrets.PIPECAT_TOKEN }}
92+
steps:
93+
- uses: actions/checkout@v4
94+
95+
- name: Install CLI
96+
run: pip install pipecatcloud
97+
98+
- name: Deploy
99+
run: pipecat cloud deploy my-agent --yes
100+
```
101+
102+
<Tip>
103+
For deployments specifically, the [Deploy to Pipecat Cloud GitHub
104+
Action](./ci-with-github-actions) uses an API key instead. PATs are useful
105+
when you need to run arbitrary CLI commands in CI (e.g. managing secrets,
106+
listing agents, or scripting multi-step workflows).
107+
</Tip>
108+
109+
### GitLab CI
110+
111+
Add `PIPECAT_TOKEN` as a CI/CD variable (Settings → CI/CD → Variables, masked):
112+
113+
```yml
114+
deploy:
115+
image: python:3.12
116+
script:
117+
- pip install pipecatcloud
118+
- pipecat cloud deploy my-agent --yes
119+
```
120+
121+
GitLab automatically exposes CI/CD variables as environment variables, so the CLI picks up `PIPECAT_TOKEN` without additional configuration.
122+
123+
## Security considerations
124+
125+
- **Treat PATs like passwords.** Anyone with your token can act as you.
126+
- **Use your CI platform's secret store.** Never commit tokens to source control.
127+
- **Scope tokens to purpose.** Create separate PATs for different pipelines so you can revoke them independently.
128+
- **Rotate periodically.** Delete old tokens from the dashboard and generate new ones.
129+
130+
## Next steps
131+
132+
<CardGroup cols={2}>
133+
<Card
134+
title="CI with GitHub Actions"
135+
icon="github"
136+
href="./ci-with-github-actions"
137+
>
138+
Automate deploys with the official GitHub Action.
139+
</Card>
140+
<Card
141+
title="Accounts and Organizations"
142+
icon="people-group"
143+
href="../fundamentals/accounts-and-organizations"
144+
>
145+
Learn about organizations, API keys, and access control.
146+
</Card>
147+
</CardGroup>

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -615,6 +615,7 @@
615615
]
616616
},
617617
"deployment/pipecat-cloud/guides/ci-with-github-actions",
618+
"deployment/pipecat-cloud/guides/personal-access-tokens",
618619
"deployment/pipecat-cloud/guides/daily-webrtc",
619620
"deployment/pipecat-cloud/guides/krisp-viva",
620621
{

0 commit comments

Comments
 (0)