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, sessions, or OAuth tokens required for the REST API.

How it works

1. You create an API key in your Perspective account (see API Keys).
2. You include the key on every HTTP request in the x-perspective-api-key header.
3. 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

curl https://api.perspective.co/v1/workspaces \
  -H "x-perspective-api-key: $PERSPECTIVE_API_KEY"

JavaScript

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();

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