Authentication

Learn how to authenticate requests to the Pivot API using your integration’s API key.

All requests to the Pivot API must be authenticated using your integration’s API key. This is done through the HTTP Authorization header.

How Authentication Works

When you make a request to the Pivot API, include your API key in the following format:

Authorization: Bearer YOUR_API_KEY

The word Bearer must be followed by a space and then your full API key.

For example, using curl:

curl ‘https://api.pivot.app/v1/spaces’ -H ‘Authorization: Bearer YOUR_API_KEY’

This key identifies the caller and controls what data and actions it has access to.

Two kinds of key

Pivot has two kinds of API key, and both authenticate exactly as above:

• An organization API key acts as the integration itself — a headless identity owned by the organization, with the roles you grant it.
• A personal API key acts as you, with the access you already have.

Which one you want depends on whether the caller should be a piece of software the organization owns or you personally. See API key types for how to choose, and for the few endpoints that accept only one of them.

Rate Limits

Authenticated API requests are limited to 60,000 requests per minute for each integration and 60,000 requests per minute across all integrations in the same organization.

Every authenticated API response includes:

• RateLimit-Limit: the applicable limit closest to being exhausted.
• RateLimit-Remaining: the number of requests remaining in that window.
• RateLimit-Reset: the number of seconds until the window resets.

When a limit is exceeded, the API returns 429 Too Many Requests and includes Retry-After with the number of seconds to wait before retrying.

Security Notes

• Keep your API key secure. Do not expose it in frontend code, public repositories, or shared documents.
• If a key is compromised, rotate it immediately.
• API keys are tied to individual integrations. If you delete the integration, the key becomes invalid.
• Rotating a key invalidates the previous one immediately.
• A personal API key carries your full account access, so treat it like your password.