Authentication Model
This document defines authentication requirements for PTI v1.0 API access.
Normative language
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119.
Authentication goals
Every API request MUST establish:
- Caller identity — which tenant or service acts.
- Credential integrity — proof the credential is valid and unrevoked.
- Freshness — protection against replay for signed requests.
Anonymous access MAY be permitted only on explicitly marked public verification endpoints.
Credential types
| Type | Use case | Transport |
|---|---|---|
| API key + secret | Server-to-server integrations | HMAC-signed requests or OAuth2 client credentials |
| Bearer access token | Short-lived session access | Authorization: Bearer header |
| mTLS client certificate | High-assurance service mesh | TLS handshake |
| Signed JWT | Federation and assertion exchange | Authorization: Bearer or detached JWS |
Interactive user sessions SHOULD NOT be embedded in producer automation; use service credentials instead.
API key authentication
HMAC request signing
Clients MUST send:
| Header | Description |
|---|---|
X-PTI-Key-Id | Public key identifier |
X-PTI-Timestamp | Unix epoch seconds |
X-PTI-Signature | Base64 HMAC-SHA256 of canonical request |
Canonical string MUST concatenate:
{method}\n{path}\n{timestamp}\n{sha256(body)}
Servers MUST reject requests with timestamp skew greater than 300 seconds.
OAuth 2.0 client credentials
Implementations SHOULD support OAuth 2.0 client credentials grant for token-oriented clients.
- Access tokens MUST expire within 24 hours (default: 1 hour).
- Refresh tokens MAY be issued for confidential clients.
- Token introspection endpoint SHOULD be available for resource servers.
Bearer tokens
Access tokens MUST be opaque or JWT with:
| Claim | Requirement |
|---|---|
sub | Service principal or tenant automation identity |
tenant_id | Owning tenant |
scope | Space-delimited scopes per Authorization Model |
exp | Expiration |
iat | Issued at |
Resource servers MUST validate exp, tenant_id, and scope on every request.
mTLS
High-assurance profiles MAY require client certificates issued by a registry-trusted CA. Certificate rotation SHOULD occur before 30-day expiry.
JWT assertion authentication
Federation partners MAY present signed JWTs for cross-registry calls. Verifiers MUST:
- Validate issuer against federation trust store
- Enforce
audmatches local registry identifier - Reject
alg: none
Credential lifecycle
| Event | Requirement |
|---|---|
| Issuance | Bind to tenant and intended profile |
| Rotation | Support overlapping valid keys for minimum 24 hours |
| Revocation | Propagate to all edge gateways within 15 minutes |
| Audit | Log issuance, rotation, revocation with actor |
Sandbox vs production
- Sandbox credentials MUST be cryptographically and logically separated from production.
- Sandbox data MUST NOT contain production PII without explicit waiver.
- Clients MUST use environment-specific base URLs; servers SHOULD reject cross-environment tokens.
Failure handling
Authentication failures MUST return PTI-401x codes without revealing whether a tenant exists.
Brute-force protection MUST apply per X-PTI-Key-Id and source IP.