Authentication
Authenticate API, CLI, and MCP requests without passing user identity in request bodies.
API keys
Send a Ploid API key with either supported header.
Authorization: Bearer $PLOID_API_KEYx-api-key: $PLOID_API_KEYPloid derives the organization and user identity from the authenticated credential. Do not send organization IDs, user IDs, cookies, or provider secrets in a public API body.
Scopes
Keys are permissioned. The primary public scopes are:
| Scope | Allows |
|---|---|
agent:chat | Run Agent tasks and inspect Agent connections |
people:search | Search the public people index |
people:enrich | Enrich supported profile and contact fields |
linkedin:read | Read the documented public LinkedIn operations |
account:read | Read usage and credits or revoke the caller key |
Scopes for private-preview or retired endpoint families are not accepted by the public API. The current operations and their required scopes are the ones published in the OpenAPI document.
An endpoint called without its required permission returns 403 with insufficient_scope.
Browser login for local tools
The CLI and MCP package support a device authorization flow. This creates and stores a narrowly scoped credential without requiring you to paste a secret into the terminal.
ploid login
npx @ploid/mcp loginFor CI and headless runtimes, inject PLOID_API_KEY from the platform's secret manager.
To revoke the calling key programmatically, send DELETE /v1/account/key with that key. A successful response is the final response it can authorize.
Key hygiene
- Create a separate key for each environment or integration.
- Give it only the scopes the integration needs.
- Configure daily or monthly budgets where available.
- Rotate a credential immediately if it appears in source control, logs, screenshots, or chat.
- Never expose an API key in browser JavaScript. Send requests through your own server.
Secrets are shown once
Ploid stores hashed key material. If you lose a secret, revoke that key and create another one; the original value cannot be displayed again.