Authentication

The public API authenticates your organization, not an individual user. Every request carries a single organization API key in the Authorization header, and everything that key touches — data, quotas, rate limits — is scoped to your org, not to whoever created the key.

Creating a key

Only an organization admin can create or revoke API keys, from the Pulse product UI under Settings → API Keys. Because a key is a standing credential, both creating and revoking one require a fresh sudo MFA re-verification — if your MFA session has lapsed, you'll be asked to re-verify before the action goes through.

When you create a key, the full plaintext value is shown to you exactly once, at creation time. Copy it immediately and store it somewhere safe (a secrets manager or environment variable) — Pulse never stores or displays the plaintext again. If you lose it, the only recovery is to revoke the key and create a new one.

Key format

A key looks like:

pulse_<8-hex-char prefix>_<secret>

For example, pulse_a1b2c3d4_<...>. The 8-character hex prefix isn't secret — it's shown next to the key's name in Settings → API Keys so you can identify which key is which without ever seeing the full secret again.

Using a key

Send the key as a bearer token on every request:

Authorization: Bearer pulse_a1b2c3d4_<secret>

curl https://api.pulseintelligence.com/v1/companies/search/ \
  -H "Authorization: Bearer pulse_a1b2c3d4_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"filters": []}'

The trailing slash is required — the API doesn't redirect a slash-less path, it 404s. Always call /v1/companies/search/, never /v1/companies/search.

Keys only work on /v1/ endpoints — they're rejected everywhere else, and conversely, the JWT tokens used elsewhere in the Pulse product are rejected on /v1/. The two auth mechanisms don't overlap.

Authentication failures

A missing header, a malformed key, an unknown key, and a revoked key all produce the same generic 401:

{ "detail": "..." }

This is deliberate: the response never tells a caller why authentication failed, so a probing request can't distinguish "this key doesn't exist" from "this key was revoked" from "you got the format wrong." Note this is DRF's stock error body, not the {"error": {"code", "message"}} envelope used elsewhere on the API — see Rate limits and errors for that envelope and the other error shapes you'll encounter.

Revoking a key

Revocation takes effect immediately — a revoked key stops authenticating on its very next use. Revoking is also idempotent: revoking an already-revoked key is a no-op, not an error.

Rotating a key

There's no in-place "regenerate" — rotate by creating a new key, updating your integration to use it, and then revoking the old one once you've confirmed the new one works. Because both steps need sudo MFA, plan a rotation as a deliberate, hands-on-keyboard action rather than something you automate unattended.

Security guidance

• Treat a key like any other server-side secret: never embed it in client-side code, a mobile app, or anything a user's browser can read.
• Store it in an environment variable or secrets manager, not in source control.
• Because a key authenticates the whole organization, anyone who has it can act as your org against every /v1/ endpoint — scope who has access to the value accordingly.
• If a key is ever exposed, revoke it immediately and create a replacement.