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 & Session Initiation

Authorize Session (GET /authorize)

Initiates the authentication handshake. The client browser is redirected to this endpoint to input credentials. Upon successful credential validation against Cloudflare D1, the Central Auth Worker issues a short-lived temporary code.

• URL: /authorize
• Method: GET
• Query Parameters:
  • client_id (string, required): The unique identifier of the registering downstream application (e.g., app_1).
  • redirect_uri (string, required): The callback URL of the application server where the code should be returned.
  • state (string, required): A cryptographically random, short-lived anti-CSRF token.

Success Response (302 Found)

Redirects the user browser back to the registered callback URL with the ephemeral authorization code:

HTTP/1.1 302 Found
Location: https://app1.com/callback?code=temp_code_abc999&state=xyz123

Error Responses

• 400 Bad Request: Missing required parameters, mismatching redirect_uri (does not match registration), or invalid client_id.
• 401 Unauthorized: Invalid user credentials entered on the login portal.

2. Backend Token Upgrade (Backchannel)

Upgrade Token (POST /api/tokens/upgrade)

Fired securely server-to-server (bypassing the browser) by the downstream application’s integration library. The application server provides its secret Application Auth Key to authenticate, alongside the user ID and the local permission bitmask mapping queried from its own database.

• URL: /api/tokens/upgrade
• Method: POST
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer sk_live_abc123... (Required Application Auth Key)

Request Body

{
  "client_id": "app_1",
  "user_id": "user_998877",
  "inject_permissions": 43
}

Success Response (200 OK)

Returns the final, long-lived access token signed using the server’s secure Ed25519 private key. The token is cryptographically bound to the client’s public key thumbprint (cnf.jkt).

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

Verification Lifecycle at /api/tokens/upgrade

1. API Key Authentication: The worker hashes the incoming Bearer secret using SHA-256 and executes a constant-time SQL lookup against the registered_applications table in Cloudflare D1.
2. Permission Rules Check: Confirms that the registered application has custom permission injection enabled (allow_custom_permissions = 1).
3. Payload Construction:
   • Bakes the user_id into the sub claim.
   • Bakes the client_id into the aud claim.
   • Embeds the inject_permissions bitmask into the permissions claim.
   • Appends the client key confirmation thumbprint (cnf.jkt) associated with the temporary session.
4. Token Signing: Signs the JWT payload using the secure Ed25519 private key.

3. Public Key Discovery

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

Exposes the public verification keys. Downstream application servers fetch and cache this set to validate token signatures 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"
    }
  ]
}

4. Resource Server Local Validation Protocol

When a downstream application server receives an API request, it performs signature validation and authorization checks locally on CPU memory, requiring no database lookups or network calls.