API & authentication

Authenticate machines with scoped credentials, not embedded master keys.

PipKey uses explicit authentication and scope checks for protected routes. Machine integrations can use environment-specific credentials with an audience, scopes and optional expiry or network restrictions.

Machine credential format

Live and test credentials are deliberately distinguishable:

pk_live_...
pk_test_...

A raw credential is returned once when it is created. PipKey stores a protected digest rather than the raw secret.

Credential verification example

The following illustrates the current service-credential verification contract. Use the API base supplied for your PipKey environment.

POST /v2/api-credentials/verify
Authorization: Bearer <PipKey machine credential>
Content-Type: application/json

{
  "audience": "your-service",
  "environment": "test",
  "requiredScopes": ["your-service:action"]
}

What PipKey checks

• Credential validity and environment.
• Expected audience.
• Required scopes.
• Optional expiry and CIDR restrictions.
• Optional linked customer, product or licence.
• Linked licence state, where a credential is bound to a licence.

Response expectations

• 401 for an invalid credential, audience mismatch or environment mismatch.
• 403 when the credential is valid but lacks required scope.
• Machine-readable errors should be handled without exposing secrets to users or logs.

Idempotency and retries

Supported retryable mutations use idempotency so a timeout does not have to create duplicate state. Reuse the same idempotency key when retrying the same logical operation.

Interactive API documentation

Interactive documentation is intentionally disabled on the accepted production 1.0 service. Approved integrators receive the applicable contract and environment details during onboarding. Public docs will expand as the 1.1 commercial developer experience is accepted.