Skip to main content

​
Initiate Login

Start OAuth flow with social provider.
​
provider
string
required
OAuth provider: google, github, or x
​
redirect
string
Redirect URL after authentication (default: /)
GET /api/zkauth/login?provider=google
Response: Redirect to OAuth provider

​
OAuth Callback

Handle OAuth callback (internal endpoint). 
GET /api/zkauth/callback/:provider
Response: Redirect to application with session

​
Get Auth Status

Check current authentication status. 
GET /api/zkauth/status
Response (authenticated): 
{
  "success": true,
  "data": {
    "authenticated": true,
    "provider": "google",
    "email": "user@example.com",
    "name": "John Doe",
    "avatar": "https://...",
    "publicKey": "0x04abc...",
    "starknet": {
      "verified": true,
      "contract": "0x123...",
      "proofExpiry": "2025-12-08T10:00:00Z"
    }
  }
}
Response (not authenticated): 
{
  "success": true,
  "data": {
    "authenticated": false
  }
}

​
Generate STARK Proof

Generate a new STARK proof for the current session. 
POST /api/zkauth/prove
Response: 
{
  "success": true,
  "data": {
    "proof": {
      "stark_proof": "0x...",
      "public_inputs": ["0x...", "0x..."],
      "cairo_version": "2.0"
    },
    "verified": true,
    "txHash": "0x456...",
    "expiresAt": "2025-12-08T10:00:00Z"
  }
}

​
Verify Session

Verify that current session has valid STARK proof. 
POST /api/zkauth/verify
Response: 
{
  "success": true,
  "data": {
    "valid": true,
    "proofExpiry": "2025-12-08T10:00:00Z",
    "starknet": {
      "contract": "0x123...",
      "verified": true
    }
  }
}

​
Refresh Proof

Refresh STARK proof before expiry. 
POST /api/zkauth/refresh
Response: 
{
  "success": true,
  "data": {
    "proof": {
      "stark_proof": "0x...",
      "public_inputs": ["0x...", "0x..."]
    },
    "txHash": "0x789...",
    "expiresAt": "2025-12-15T10:00:00Z"
  }
}

​
Logout

End session and revoke STARK proof. 
POST /api/zkauth/logout
Response: 
{
  "success": true,
  "data": {
    "loggedOut": true,
    "proofRevoked": true
  }
}

​
Get Supported Providers

List available OAuth providers. 
GET /api/zkauth/providers
Response: 
{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "google",
        "name": "Google",
        "icon": "google",
        "enabled": true
      },
      {
        "id": "github",
        "name": "GitHub",
        "icon": "github",
        "enabled": true
      },
      {
        "id": "x",
        "name": "X (Twitter)",
        "icon": "x-twitter",
        "enabled": true
      },
      {
        "id": "apple",
        "name": "Apple",
        "icon": "apple",
        "enabled": false
      }
    ]
  }
}
Link additional OAuth provider to existing account.
​
provider
string
required
Provider to link
GET /api/zkauth/link?provider=github
Response: Redirect to OAuth provider
Remove linked OAuth provider (must keep at least one).
​
provider
string
required
Provider to unlink
POST /api/zkauth/unlink
Request: 
{
  "provider": "github"
}
Response: 
{
  "success": true,
  "data": {
    "unlinked": true,
    "provider": "github",
    "remainingProviders": ["google"]
  }
}

​
Error Codes

CodeDescription
PROVIDER_UNAVAILABLEOAuth provider not available
AUTH_FAILEDOAuth authentication failed
SESSION_EXPIREDSession has expired
PROOF_EXPIREDSTARK proof has expired
PROOF_GENERATION_FAILEDFailed to generate STARK proof
CANNOT_UNLINKCannot unlink last provider
STARKNET_ERRORStarknet verification failed