Authentication

API keys

Every request to the Ploton API needs an API key in the Authorization header.

curl https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer pk_live_your_api_key_here"

You can generate and rotate API keys from the Ploton dashboard.

Key types

Both key types go through the same Ploton pipeline — tool selection, workflow generation, execution. The only difference is how connected services respond. Test keys are safe to use in CI, staging, and during development.

Key security

• Store API keys in environment variables or a secrets manager. Don’t commit them to source control.
• Each key has full access to your Ploton account. There are no per-key scope restrictions today, so treat them like passwords.
• If a key leaks, rotate it from the dashboard. Revocation takes effect immediately.

# Good — key in environment variable
export PLOTON_API_KEY="pk_live_your_api_key_here"

# Bad — key hardcoded in source
const apiKey = "pk_live_abc123"; // Don't do this

Webhook secrets

Webhook secrets let you verify that incoming requests are from Ploton and not someone who found your endpoint URL.

Your webhook secret is in the dashboard next to your API keys.

export PLOTON_WEBHOOK_SECRET="whsec_your_webhook_secret_here"

Ploton signs every webhook payload with your secret using HMAC-SHA256 and puts the signature in the X-Ploton-Signature header. See Webhooks: Webhook Security for verification code in several languages.

Always verify webhook signatures in production. Without verification, anyone who finds your endpoint URL can send fake events.

OAuth (managed by Ploton)

When a task involves a third-party service that requires user authorization, Ploton handles the OAuth flow.

How it works

sequenceDiagram
    participant Agent
    participant Ploton
    participant Service
    participant User

    Agent->>Ploton: Create task
    Ploton->>Service: Check authorization
    Service-->>Ploton: Not authorized
    Ploton-->>Agent: task.waiting + auth_url
    Agent->>User: Present auth_url
    User->>Service: Complete OAuth consent
    Service-->>Ploton: Authorization granted
    Ploton->>Service: Execute task
    Service-->>Ploton: Result
    Ploton-->>Agent: task.complete

1. Your agent creates a task that touches a service the user hasn’t authorized yet
2. Ploton detects the missing authorization and pauses the task (waiting status)
3. Ploton sends a task.waiting webhook with an auth_url
4. Your app shows the auth_url to the user — browser redirect, email, push notification, whatever fits
5. The user completes the OAuth consent flow
6. Ploton stores the tokens and resumes the task

{
	"event": "task.waiting",
	"task_id": "task_8xK2mP",
	"data": {
		"reason": "oauth_consent_required",
		"service": "crm",
		"auth_url": "https://ploton.ai/auth/crm?session=sess_abc123"
	}
}

Token management

Once a user authorizes a service, Ploton manages the tokens:

• Token storage — encrypted at rest, isolated per user
• Token refresh — automatic refresh before expiry, transparent to your agent
• Scope management — if a new task needs additional scopes, Ploton prompts for incremental authorization
• Revocation — users can revoke from the Ploton-hosted settings page, or you can revoke via the API

Your agent never sees raw tokens.

Supported providers

OAuth works for all services with built-in tools. See the Tools page for the full list. Custom tools can declare their own OAuth requirements — see Registering Custom Tools.

Environment variable reference

Next steps

• API Overview — Base URL, response format, rate limits
• Webhooks — Webhook delivery and signature verification