PingRepDocs

Reference

API Keys

Create, manage, and secure API keys for programmatic access to the PingRep API.

Overview

API keys provide long-lived authentication for server-to-server integrations. Unlike JWT tokens (which are tied to user sessions), API keys are designed for automated systems, background jobs, and third-party integrations.

Every API key has a set of scopes that control which endpoints it can access. Keys follow the format sk_live_... and are only displayed once at creation time.

Store keys securely

The full API key is returned only once when you create it. Store it immediately in a secure location like a secrets manager or environment variable. You cannot retrieve it again.

Create a key

POST
/api/v1/api-keys
JWT

Creates a new API key with the specified name, scopes, and optional expiration.

Request body:

namestringRequired

A human-readable label for this key (e.g., "Production Backend").

scopesstring[]Required

Array of permission scopes. Use GET /api/v1/api-keys/scopes to list available scopes.

tierstringRequired

The tier this key operates at. Must match or be below your account tier.

expiresAtstringOptional

ISO 8601 expiration date. If omitted, the key does not expire.

List keys

Retrieve all API keys for the authenticated user. The key value itself is not included in the response for security.

GET
/api/v1/api-keys
JWT

Returns all API keys with their names, scopes, and status. The key secret is never returned.

List available scopes

GET
/api/v1/api-keys/scopes
JWT

Returns all available permission scopes you can assign to an API key.

Rotate a key

Rotation generates a new key secret while keeping the same key ID and scopes. The old secret is invalidated immediately.

POST
/api/v1/api-keys/{key_id}/rotate
JWT

Generates a new secret for the key. The old secret stops working immediately.

Zero-downtime rotation

To avoid downtime during rotation, create a new key first, update your systems to use it, then revoke the old key. The rotate endpoint invalidates the old secret immediately.

Check usage

Monitor how many requests a specific API key has made.

GET
/api/v1/api-keys/{key_id}/usage
JWT

Returns request counts, last used timestamp, and usage breakdown by endpoint.

Revoke a key

Permanently disable an API key. This action cannot be undone. Any request using the revoked key will receive a 401 Unauthorized response.

DELETE
/api/v1/api-keys/{key_id}
JWT

Permanently revokes the API key. This cannot be undone.

Security best practices

  1. Use the narrowest scopes possible. Only grant the scopes your integration actually needs. A key that only reads profiles should not have profile:write.

  2. Set expiration dates. Keys without expiration are convenient but risky. Rotate or expire keys on a regular schedule (every 90 days recommended).

  3. Never commit keys to source control. Use environment variables or a secrets manager. If a key is accidentally exposed, revoke it immediately and create a new one.

  4. Use separate keys per environment. Create distinct keys for development, staging, and production. This limits blast radius if a key is compromised.

  5. Monitor usage regularly. Check the usage endpoint to detect unusual patterns that might indicate a compromised key.

Compromised key?

If you suspect a key has been leaked, revoke it immediately using the DELETE endpoint and create a new one. There is no way to "un-leak" a secret.