API Reference: NexID Auth-DPoP Endpoints

This document specifies the REST API endpoints and validation protocols exposed by NexID Auth-DPoP. All authentication endpoints are edge-native, designed to run globally with minimal latency.

1. Authentication & Token Management

Register User/Client (POST /auth/register)

Registers a new user and ensures they are added to the primary database and the Bloom Filter fast-path cache.

• URL: /auth/register
• Method: POST
• Headers:
  • Content-Type: application/json

Request Body

{
  "email": "user@example.com",
  "password": "SecurePassword123"
}

Success Response (201 Created)

{
  "id": "usr_9f81a7b4c6",
  "email": "user@example.com",
  "created_at": 1780339200
}

Error Responses

• 400 Bad Request: Missing required fields or weak password.
• 409 Conflict: Email already registered.

Issue Token (POST /auth/token)

Exchanges user credentials for a DPoP-bound Access Token. The client must supply a valid DPoP Proof signed by their ephemeral key pair.

• URL: /auth/token
• Method: POST
• Headers:
  • Content-Type: application/x-www-form-urlencoded
  • DPoP: <DPoP-Proof-JWT> (Required)

Request Body

grant_type=password&username=user@example.com&password=SecurePassword123

Success Response (200 OK)

{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImF1dGgtay0xIn0.ey... (Ed25519 Signed JWT)",
  "token_type": "DPoP",
  "expires_in": 3600
}

Verification Lifecycle at /auth/token

1. Pre-flight Filter Check: The worker checks the email against the local Bloom Filter. If it misses, it returns 401 Unauthorized without querying Cloudflare D1.
2. DPoP Proof Verification:
   • The DPoP header JWT signature is verified using the public key (jwk) in its header.
   • The payload htm (HTTP Method) must be POST and htu (HTTP URI) must match the endpoint (https://<domain>/auth/token).
   • The jti claim is verified against Upstash Redis to ensure it hasn’t been replayed.
3. User Authentication:
   • Queries Cloudflare D1 to verify the password hash using PBKDF2/argon2.
4. Token Generation:
   • Generates the JWK thumbprint (jkt) of the client’s public key.
   • Merges the user’s roles and permissions from D1 into a single bitmask integer.
   • Signs the JWT using the server’s private Ed25519 key.

2. Key Discovery

JSON Web Key Set (GET /.well-known/jwks.json)

Exposes the public keys used by the NexID Auth server. Resource servers fetch and cache this set to perform signature checks locally.

• URL: /.well-known/jwks.json
• Method: GET

Success Response (200 OK)

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "kid": "auth-k-1",
      "use": "sig",
      "x": "11qYAYGgCrfVS_7TyyHO-UU0FpH-x9G_z6c5D5nVoYo"
    }
  ]
}

3. Resource Server Local Validation Protocol

When a resource server receives an API request, it validates the credentials locally on CPU memory using the following checklist.