CLI authentication

Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules.

This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

Authentication methods

Method	Admin API	Control/data plane	Best for
User login	✅	✅	Interactive use
Service account	✅	✅	Automation with Admin API access
API key	❌	✅	Simple automation, CI/CD

Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity).

Bash

pc auth login

The CLI auto-targets your default organization and its first project. Change with pc target -o "my-org" -p "my-project".

Service account

Authenticate with credentials from a service account.

Bash

pc auth configure --client-id "ID" --client-secret "SECRET"

# Or via environment variables
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"

The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with pc target -p "my-project".

API key

Authenticate with an API key. API keys can't access the Admin API.

Bash

pc auth configure --api-key "YOUR_API_KEY"

# Or via environment variable
export PINECONE_API_KEY="your-api-key"

Auth priority

When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration.

Control/data plane operations:

API key
User login token (via managed keys)
Service account (via managed keys)

Admin API operations:

User login token
Service account

Example scenarios:

If PINECONE_API_KEY is set, the CLI uses it for control/data plane operations, regardless of any stored API key.
If you're logged in via pc auth login and also have PINECONE_CLIENT_ID/PINECONE_CLIENT_SECRET set, the user login token is used for everything—the service account env vars are ignored.
If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API).

Managed keys

When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use.

Stored locally: ~/.config/pinecone/secrets.yaml (permissions 0600)
Stored remotely: Visible in console as pinecone-cli-{id} with origin cli_created

Bash

# List locally tracked managed keys
pc auth local-keys list

# Delete managed keys (local + remote)
pc auth local-keys prune

# Delete only CLI-created managed keys
pc auth local-keys prune --origin cli

# Delete only user-created managed keys
pc auth local-keys prune --origin user

# Delete a specific API key by ID
pc api-key delete --id "KEY_ID"

Logging out

Bash

pc auth logout

Clears all local auth data: tokens, credentials, API keys, managed keys, and target context.

Local storage

Auth data is stored in ~/.config/pinecone/ with 0600 permissions:

File	Contents
`secrets.yaml`	OAuth token, service account credentials, API keys, managed keys
`state.yaml`	Target org/project
`config.yaml`	CLI settings (color, environment)

Check status

Bash

pc auth status

Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration.