REST API — Authentication

Every Personyze REST API request must be authenticated with an API key, transmitted over HTTPS. There are no public/unauthenticated endpoints.

If you haven’t read it yet, start with the REST API Overview & Quick Start for the high-level shape of every request.

Where to find your API key

In the Personyze admin GUI, go to Settings → Integrations → API. Each Personyze account you have access to has its own key — they’re not interchangeable.

How to send the key

Use HTTP Basic Authentication with username api and the key as the password. Two common ways to do this:

Curl shortcut — credentials in the URL

Convenient for ad-hoc testing and shell scripts:

curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'

Authorization header — preferred for production code

Most HTTP client libraries don’t reliably parse user:pass@host from URLs, and putting credentials in the URL leaks them into webserver logs and browser history. For production code, build the Authorization header explicitly:

Authorization: Basic <base64("api:" + API_KEY)>

Curl with explicit header

curl https://app.personyze.com/rest/users/where/internal_id=42 \
     -H "Authorization: Basic $(printf 'api:%s' YOUR_API_KEY | base64)"

Python (requests)

import requests

r = requests.get(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    auth=('api', YOUR_API_KEY),
)
r.raise_for_status()
data = r.json()

JavaScript (fetch)

const r = await fetch(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    { headers: { Authorization: 'Basic ' + btoa('api:' + API_KEY) } }
);
const data = await r.json();

Authentication error codes

Multi-account / multi-tenant access

The API key encodes which Personyze account the request operates on. The endpoint URL never names the account — it’s inferred from the key. To work against several accounts from the same client, hold one key per account and pick the right one before each request.

Object IDs are scoped per account too: action 42 in account A is unrelated to action 42 in account B. If your code stores Personyze IDs alongside your own data, you’ll want to also store the account ID (or at least which API key created them) so you can later re-issue requests against the right account.

Rate limiting & timeouts

• Tracker / SDK fast-path requests are budgeted at 10 seconds of execution. Longer requests are force-disconnected with a 503-eligible error. Most REST API calls aren’t on this fast path, but be aware that complex queries on large tables may need careful indexing to stay under the limit.
• POST /rest/users is throttled per account: at most one in-flight insert at a time. Beyond a 1-second queue wait, requests are rejected with 400 Too many simultaneous requests. Retry with exponential backoff. (This is documented further on the users object page.)
• Other endpoints are not currently rate-limited at the application level — but treat the API as a shared resource and avoid hammering it from many parallel processes when sequential calls would do.

Next steps