Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Authentication API

WebAuthn/Passkey authentication endpoints for secure passwordless login.

Registration Flow

1. Get Registration Options

POST /auth/register/options
Content-Type: application/json
 
{
  "email": "user@example.com"
}
Response: 
{
  "challenge": "base64-encoded-challenge",
  "rp": {
    "name": "Vault",
    "id": "vault.oxc.sh"
  },
  "user": {
    "id": "base64-user-id",
    "name": "user@example.com",
    "displayName": "user@example.com"
  },
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -7 },
    { "type": "public-key", "alg": -257 }
  ],
  "authenticatorSelection": {
    "residentKey": "required",
    "userVerification": "required"
  }
}

2. Verify Registration

POST /auth/register/verify
Content-Type: application/json
 
{
  "email": "user@example.com",
  "credential": {
    "id": "credential-id",
    "rawId": "base64-raw-id",
    "response": {
      "attestationObject": "base64-attestation",
      "clientDataJSON": "base64-client-data"
    },
    "type": "public-key"
  }
}
Response: 
{
  "token": "jwt-token",
  "userId": "user-uuid",
  "email": "user@example.com"
}

Login Flow

1. Get Login Options

POST /auth/login/options
Content-Type: application/json
 
{
  "email": "user@example.com"
}
Response: 
{
  "challenge": "base64-challenge",
  "allowCredentials": [
    {
      "id": "base64-credential-id",
      "type": "public-key",
      "transports": ["internal", "hybrid"]
    }
  ],
  "userVerification": "required",
  "rpId": "vault.oxc.sh"
}

2. Verify Login

POST /auth/login/verify
Content-Type: application/json
 
{
  "email": "user@example.com",
  "credential": {
    "id": "credential-id",
    "rawId": "base64-raw-id",
    "response": {
      "authenticatorData": "base64-auth-data",
      "clientDataJSON": "base64-client-data",
      "signature": "base64-signature"
    },
    "type": "public-key"
  }
}
Response: 
{
  "token": "jwt-token",
  "userId": "user-uuid",
  "email": "user@example.com"
}

CLI Authentication

The CLI cannot perform WebAuthn directly and uses browser delegation:

1. Create CLI Session

POST /auth/cli/session
Response: 
{
  "sessionId": "session-uuid",
  "expiresAt": "2024-01-01T00:05:00Z"
}

2. Poll Session Status

GET /auth/cli/session/:id
Response (pending): 
{
  "status": "pending"
}
Response (complete): 
{
  "status": "complete",
  "token": "jwt-token",
  "userId": "user-uuid",
  "email": "user@example.com"
}

3. Complete Session (called by web app)

POST /auth/cli/session/:id/complete
Authorization: Bearer <token>
Response: 
{
  "success": true
}

Session States

StateDescription
pendingWaiting for user to authenticate in browser
completeAuthentication successful, token available
errorAuthentication failed
expiredSession TTL exceeded (5 minutes)

Session Management

Check Session Status

GET /auth/session/status
Authorization: Bearer <token>
Response: 
{
  "valid": true,
  "userId": "user-uuid",
  "email": "user@example.com"
}

Logout

POST /auth/session/logout
Authorization: Bearer <token>
Response: 
{
  "success": true
}

Sharing Keys

For vault sharing, users need ECDH key pairs:

Store Sharing Keys

POST /auth/sharing-keys
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "publicKey": "base64-public-key",
  "encryptedPrivateKey": "base64-encrypted-private"
}

Get Own Sharing Keys

GET /auth/sharing-keys
Authorization: Bearer <token>
Response: 
{
  "publicKey": "base64-public-key",
  "encryptedPrivateKey": "base64-encrypted-private"
}

Get User's Public Key

GET /auth/user/:email/public-key
Authorization: Bearer <token>
Response: 
{
  "publicKey": "base64-public-key"
}

Error Responses

Invalid Credentials

{
  "error": "Invalid credentials",
  "code": "INVALID_CREDENTIALS"
}

User Not Found

{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}

Session Expired

{
  "error": "Session expired",
  "code": "SESSION_EXPIRED"
}

Related