zkAuth API - zkTerm Documentation

Start OAuth flow with social provider.

string

required

OAuth provider: google, github, or x

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 Provider

Link additional OAuth provider to existing account.

string

required

Provider to link

GET /api/zkauth/link?provider=github

Response: Redirect to OAuth provider

Unlink Provider

Remove linked OAuth provider (must keep at least one).

string

required

Provider to unlink

POST /api/zkauth/unlink

Request:

{
  "provider": "github"
}

Response:

{
  "success": true,
  "data": {
    "unlinked": true,
    "provider": "github",
    "remainingProviders": ["google"]
  }
}

Error Codes

Code	Description
`PROVIDER_UNAVAILABLE`	OAuth provider not available
`AUTH_FAILED`	OAuth authentication failed
`SESSION_EXPIRED`	Session has expired
`PROOF_EXPIRED`	STARK proof has expired
`PROOF_GENERATION_FAILED`	Failed to generate STARK proof
`CANNOT_UNLINK`	Cannot unlink last provider
`STARKNET_ERROR`	Starknet verification failed

​Initiate Login

​OAuth Callback

​Get Auth Status

​Generate STARK Proof

​Verify Session

​Refresh Proof

​Logout

​Get Supported Providers

​Link Provider

​Unlink Provider

​Error Codes

Initiate Login

OAuth Callback

Get Auth Status

Generate STARK Proof

Verify Session

Refresh Proof

Logout

Get Supported Providers

Link Provider

Unlink Provider

Error Codes