Authentication
Every request to the Perspective External API must be authenticated with an API key passed in the x-perspective-api-key request header. There are no cookies or sessions. A signed-in user's OAuth access token works too (see Bearer tokens); the CLI uses it when you sign in with your browser.
How it works
- You create an API key in your Perspective account (see API Keys).
- You include the key on every HTTP request in the
x-perspective-api-keyheader. - Perspective validates the key, checks your permissions and subscription, and either fulfils the request or returns an error.
If the header is absent or the key is invalid, the API responds with 401 Unauthorized. If the key is valid but lacks the necessary permissions, you receive 403 Forbidden. See Errors for the full status-code reference.
Making an authenticated request
The example below calls GET /v1/workspaces — a convenient first call to verify that your key works and to discover the workspaces and funnel IDs available to you. The examples assume you have stored your key in a PERSPECTIVE_API_KEY environment variable (see API Keys).
- cURL
- JavaScript
curl https://api.perspective.co/v1/workspaces \
-H "x-perspective-api-key: $PERSPECTIVE_API_KEY"
const response = await fetch('https://api.perspective.co/v1/workspaces', {
headers: {
'x-perspective-api-key': process.env.PERSPECTIVE_API_KEY,
},
});
if (!response.ok) {
const err = await response.json();
throw new Error(`${err.status}: ${err.error}`);
}
const { data } = await response.json();
Bearer tokens
The access token issued by the OAuth flow the MCP server uses also authenticates REST requests:
Authorization: Bearer <access token>
The request then acts as the signed-in user: it sees the workspaces and funnels that user can open in the app, and may read and write contacts and read metrics. Like an API key, it needs a plan that includes the External API for the contact and metrics endpoints; on other plans those requests are rejected with 403. API keys keep their own permissions. When both headers are sent, the API key is used. A funnel's revision history and HTML are available to a signed-in user only: an API key is refused there with 403.
Best practices
- Keep the key server-side. Never embed your API key in client-side JavaScript, mobile apps, or public repositories. Treat it like a password.
- Use environment variables. Store keys in environment variables or a secrets manager rather than hard-coding them.
- Rotate regularly. If a key is compromised, regenerate it immediately from Account Settings and update all services that use it.
Related pages
- API Keys — how to obtain and manage keys
- Errors — authentication and authorization error codes
- API Reference — full endpoint catalog