Skip to main content
This feature is in public preview.
This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources.

​
Authenticating

There are three ways to authenticate the Pinecone CLI: through a web browser with user login, using a service account, or with an API key. This table describes the Pinecone operations supported by each authentication method:
MethodAdmin APIControl plane
User login✅✅
Service account✅✅
API key❌✅
  • Admin API–related commands (organization and project management, API key operations):
    • pc organization (list, describe, update, delete)
    • pc project (create, list, describe, update, delete)
    • pc api-key (create, list, describe, update, delete)
  • Control plane–related commands (index management):
    • pc index (create, list, describe, configure, delete)
Commands for data plane operations will be added in a future release.

​
User login

User login requires you to authenticate through a web browser. Subsequent CLI requests use a locally stored auth token that expires after 30 minutes but refreshes automatically. After 24 hours, you must re-authenticate. 
# Authenticate in a web browser
pc auth login
When you authenticate with pc auth login, the CLI automatically targets:
  • The default organization returned by the server for your user.
  • The first project in the list of that organization’s projects.
However, you can change organization and project as needed: 
pc auth target -o "my-org" -p "my-project"
When you authenticate with user login, the CLI uses managed API keys for control plane operations, unless you’ve set a default API key.
To learn more about targeting organizations and projects, see CLI target context. To understand how the CLI prioritizes authentication methods, see Auth priority.

​
Service account

To authenticate with a service account, provide a client ID and secret associated with a service account. 
pc auth configure --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_CLIENT_SECRET"

# Or specify a project directly
pc auth configure --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_CLIENT_SECRET" --project-id "YOUR_PROJECT_ID"
Or set these environment variables: 
export PINECONE_CLIENT_ID="your-client-id"
export PINECONE_CLIENT_SECRET="your-client-secret"
When you authentiate with a service account:
  • If your organization has only one project, the CLI automatically targets that project.
  • If your organization has multiple projects, the CLI prompts you to select a project (or you can use the --project-id flag, as shown above).
  • If your organization has no projects, create one. Then, set it as the target: 
    # Specify a project
pc target -p "my-project"
# Select a project interactively
pc target
When you authenticate with a service account, the CLI uses managed API keys for control plane operations, unless you’ve set a default API key.
To learn more about targeting organizations and projects, see CLI target context. To understand how the CLI prioritizes authentication methods, see Auth priority.

​
API key

You can also use an API to authenticate the CLI with Pinecone. This is useful for automation or CI/CD scenarios where you can’t use interactive user login or a service account. Since each API key is associated with a specific project, the CLI uses that key’s project for all operations. A default (manually specified) API key overrides any target context you’ve set — you don’t need to run pc target. 
pc auth configure --api-key "YOUR_API_KEY"
Or set this environment variable: 
export PINECONE_API_KEY="YOUR_API_KEY"
Because API keys are associated with a specific organization and project, they do not require target context. Also, to understand how the CLI prioritizes authentication methods, see Auth priority.

​
Auth priority

The CLI chooses which authentication method to use based on the type of operation.

​
Control plane operations (indexes)

Control plane operations prioritize authentication credentials in the following order:
  1. Default API key - Uses the project associated with the key.
  2. User login token - Creates and uses managed keys.
  3. Service account - Creates and uses managed keys.

​
Admin API operations (organizations, projects, API keys)

Admin API operations prioritize authentication credentials in the following order:
  1. User login token
  2. Service account
Default API keys do not provide Admin API access.

​
Environment variables vs. stored configuration

Within each credential type, environment variables always override stored configuration:
  • PINECONE_API_KEY (env var) overrides default API key stored via pc auth configure --api-key.
  • PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET (env vars) override service account credentials stored via pc auth configure.
  • User login tokens have no environment variable equivalent. They’re always stored locally.
Example scenarios:
  • If PINECONE_API_KEY (env var) is set, the CLI uses it for control plane operations, regardless of any stored default API key value.
  • If you’re logged in via pc auth login and also have PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET set:
    • Control plane operations: User login token is used (creates managed keys).
    • Admin API operations: User login token is used.
    • The service account env vars are ignored.
  • If you have a default API key stored via pc auth configure --api-key and are also logged in through the web browser:
    • Control plane operations: Default API key is used.
    • Admin API operations: User login token is used.
Environment variables are never persisted to local storage. They only override stored values at runtime.

​
Default API keys and target context

Default (manually specified) API keys override any target context. Control plane operations always use the project associated with the API key, regardless of what you’ve set with pc target.
When you set a default API key (via pc auth configure --api-key or PINECONE_API_KEY):
  • The default API key is used for control plane operations.
  • Managed keys are not created.
  • If you also have user login or service account credentials, those are still used for Admin API operations.
Setting a default API key (via pc auth configure --api-key or PINECONE_API_KEY) does not clear user login tokens or service account credentials.

​
User login and service accounts

User login and service accounts are mutually exclusive when configured via CLI commands:
  • Running pc auth login clears any stored service account credentials.
  • Running pc auth configure --client-id --client-secret clears the stored auth token from pc auth login.
However, if you set service account environment variables (PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET) without running pc auth configure, the CLI does not clear your stored user login token.
User login and service accounts both use managed keys for control plane operations (unless you’ve set a default API key).

​
Clearing credentials (logging out)

To clear your authentication credentials: 
pc auth logout
This command clears local data:
pc auth logout does not delete managed API keys from Pinecone’s servers. Those keys remain active and can be used to access your projects. To fully clean up, run pc auth local-keys prune before logging out. See Deleting API keys for details.

​
Managed keys

When authenticated with user login or a service account, the CLI automatically creates and manages API keys for control plane operations. This happens transparently, the first time you run a control plane command like pc index list. You don’t need to create or manage these keys yourself.

​
When managed keys are created

Managed keys are created only when you’re authenticated via user login or service account, and there’s no default (manually specified) API key set. After authenticating, the first time you run a control plane command like pc index list:
  1. The CLI checks if a managed key already exists locally for the target project.
  2. If not found, the CLI creates a new API key via the Admin API.
  3. The key is stored both remotely (in Pinecone) and locally for future use.
Subsequent commands targeting the same project reuse the stored key.
If you set a default API key, managed keys are not created. The default API key is used instead.

​
Where managed keys are stored

Managed API keys are stored locally and remotely:
  • Local: Stored in ~/.config/pinecone/secrets.yaml under the project_api_keys field as plain text, with file permissions set to 0600 (owner read/write only). For more details, see Local data storage.
  • Remote: Stored in Pinecone as regular API keys, visible in the web console.
The CLI will not display managed API keys after they’re created.

​
Identifying managed keys

In the Pinecone web console, CLI-created keys have:
  • Name: pinecone-cli-{6-character-alphanumeric} (for example, pinecone-cli-a3f9k2)
  • Origin: cli_created
To list all managed keys stored locally: 
pc auth local-keys list
This shows managed keys tracked in your local secrets.yaml file, including which projects they belong to.

​
Deleting API keys

There are a few ways to use the CLI to delete API keys (managed or not), locally and remotely. Delete locally tracked managed keys (local and remote): The pc auth local-keys prune command deletes managed keys that are tracked in your local secrets.yaml file. It does not affect API keys that were created outside the CLI or aren’t tracked locally. 
# Delete all locally tracked managed keys (CLI-created and user-created)
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 (local and remote): 
pc api-key delete --id "YOUR_API_KEY_ID"
This deletes any API key (managed or not) and cleans up the local record if it exists. Automatic deletion when creating a new key: When you run pc api-key create --store for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one. This prevents accumulating multiple managed keys per project.
pc auth logout deletes only the local references to managed keys. The keys remain active remotely in Pinecone. To fully clean up, run pc auth local-keys prune before logging out.

​
Local data storage

Authentication data is stored in ~/.config/pinecone/ with restricted permissions (0600): secrets.yaml - Sensitive data:
  • oauth2_token: Token associated with a user login (pc auth login)
  • client_id, client_secret: Service account credentials
  • api_key: Default (manually specified) API key
  • project_api_keys: Managed keys per project
state.yaml - Context:
  • target_org: Current organization (name and ID)
  • target_project: Current project (name and ID)
config.yaml - Settings:
  • color: Enable/disable colored output
  • environment: Production or staging

​
Check authentication status

pc auth status
Shows:
  • Current authentication method
  • Target organization and project
  • Token expiration (for user login)
  • Environment configuration