Skip to content

Commit 40a05fa

Browse files
mattshepmattshep
committed
docs: add Personal Access Tokens user guide
New guide covering PAT creation, PIPECAT_TOKEN env var usage, use-pat command, and CI/CD examples (GitHub Actions, GitLab). Also adds the missing use-pat command reference to the auth CLI docs.
1 parent e92c38d commit 40a05fa

3 files changed

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