Authentication

Authenticate every request with a bearer token:

curl https://api.proppertrading.com/v1/ping \
  -H "Authorization: Bearer sk_live_a1b2c3d4_9f83c2e15b7a4d6e8091c3f5a7b9d1e2"

A key looks like this:

sk_live_a1b2c3d4_9f83c2e15b7a4d6e8091c3f5a7b9d1e2
   |    |        |
   |    |        secret, shown once
   |    key id, safe to log and quote in support tickets
   environment

Only the key id is stored in readable form on our side. The secret is stored as a hash, which is why we cannot show it to you again.

Creating a key

In your dashboard, go to Platform -> API keys and create one. You choose:

• Scopes - what the key may do. Grant the minimum the integration needs.
• IP allowlist - optional. Only these addresses may use the key, one IPv4 or IPv6 address or CIDR range per line, at most 50.
• Expiry - optional. The key stops working once it has passed.

Scopes, the allowlist and the expiry can be changed later without a new secret. The change applies to the next call.

The secret is shown exactly once, right after you create it.

The other kind of credential

Everything on this page is about API keys, which act as a firm. There is a second kind that acts as a person on a device, used by the Propper apps and by anybody scripting on their own behalf. It starts with ptat_, it is handed out by signing in rather than generated in a dashboard, and it can never hold the scopes below.

See Signing in as a person.

Scopes

Scopes are resource:action. A :write scope also grants the matching :read, so a key that may create affiliates can also list them.

A key that authenticates but lacks the scope gets 403 insufficient_scope, and the response tells you which scope was required. Do not retry with a different key; ask your firm to widen this one.

Rotating and revoking

Rotating gives the key a new secret and keeps its key id, scopes and history. Whoever rotates chooses how long the old secret keeps working beside the new one: not at all, an hour, a day or a week. While both work, a call with either is accepted and answered the same, so to switch over without downtime:

1. Rotate with the old secret working long enough to deploy.
2. Deploy the new secret.
3. Let the old one run out, or stop it from the dashboard once nothing uses it.

A key has at most two working secrets. Rotating again while an old secret still works stops that one at once. When a secret leaked, rotate with the old one stopping now.

Revoking takes effect immediately, stops both secrets, and cannot be undone.

When something is wrong

Credentials are only accepted in the Authorization header. Query-string credentials are rejected on purpose: they leak into access logs, browser history and referrer headers.