# Prism Auth - Authentication-as-a-Service API

> Authentication-as-a-Service API for browser agents. Currently supports login with username/password, with additional features in development.

## Overview

Prism Auth provides Authentication-as-a-Service for browser agent developers. Instead of maintaining complex login scripts for arbitrary websites, agents can use our API to get live authenticated browser sessions.

**Core Value Proposition:**
- Zero login script maintenance for username/password authentication
- Universal website support  
- Live session delivery (cookies, localStorage, etc.)
- Organization-scoped multi-tenancy

## Current Capabilities

**Available Now:**
- POST /login with password, oauth_google, otp_email, magic_link authentication

**In Development:**
- POST /signup for account creation
- POST /refresh for session renewal
- Additional authentication methods (OAuth GitHub, SMS OTP, TOTP)

## Getting Started

1. **Get API Key**: Visit https://prismai.sh/workspace to generate your organization-scoped API key (starts with `pk_`)
2. **Store Securely**: Keep your API key in environment variables, never in client-side code
3. **Make API Calls**: Use Bearer token authentication for all requests

```bash
Authorization: Bearer pk_your_actual_api_key_here
```

## Available Endpoint

### POST /login
Authenticate users with existing username/password credentials and receive live session cookies. Supports optional additional fields for custom login parameters.

**Request:**
```json
{
  "cred": {
    "username": "user@example.com",
    "password": "userPassword123"
  },
  "loginMethod": "password",
  "domain": "https://github.com/login",
  "additionalFields": {
    "account": "primary",
    "lastName": "Smith"
  },
  "useCache": true
}
```

**Parameters:**
- `useCache` (boolean, optional): Whether to use cached sessions. Default: `true`
  - `true`: Returns cached session cookies if available (faster, cost-effective)
  - `false`: Forces fresh authentication through browser automation

**Response:**
```json
{
  "cookies": [
    {
      "name": "session_id",
      "value": "xyz789abc123...",
      "domain": "github.com",
      "path": "/",
      "expires": 1791936891,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "origins": []
}
```

### Endpoints In Development

**POST /signup** - Account creation with email verification  
**POST /refresh** - Session refresh using stored credentials

## Authentication Methods

**Available Now:**
- **password**: Username/password login (loginMethod: "password")
- **oauth_google**: Google OAuth login (loginMethod: "oauth_google")
- **otp_email**: Email OTP login (loginMethod: "otp_email")
- **magic_link**: Magic link login (loginMethod: "magic_link")

**In Development:**
- OAuth flows (GitHub)
- OTP (SMS)
- TOTP authenticator apps

## Usage Example

```javascript
// Step 1: Get API key from https://prismai.sh/workspace
const API_KEY = process.env.PRISM_AUTH_API_KEY; // pk_your_key_here

// Step 2: Authenticate user (with caching enabled by default)
const loginResponse = await fetch("https://prismai.sh/api/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`
  },
  body: JSON.stringify({
    cred: {
      username: "user@example.com",
      password: "userPassword123"
    },
    loginMethod: "password",
    domain: "https://github.com/login",
    additionalFields: {
      account: "primary",
      lastName: "Smith"
    },
    useCache: true // Optional: use cached session if available (default)
  })
});

// Alternative: Force fresh authentication
const freshLoginResponse = await fetch("https://prismai.sh/api/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`
  },
  body: JSON.stringify({
    cred: {
      username: "user@example.com",
      password: "userPassword123"
    },
    loginMethod: "password",
    domain: "https://github.com/login",
    useCache: false // Force fresh authentication
  })
});

const { cookies } = await loginResponse.json();

// Step 3: Apply cookies to browser context
cookies.forEach(cookie => {
  browser.setCookie(cookie);
});

// Step 4: Use authenticated browser session
await browser.goto("https://github.com/dashboard");
```

## Error Handling

**Common HTTP Status Codes:**
- `200`: Success
- `400`: Invalid request (missing required fields, invalid format)
- `401`: Authentication failed (invalid credentials or API key)
- `409`: User already exists (signup endpoint)

**Error Response Format:**
```json
{
  "error": "AUTHENTICATION_FAILED",
  "message": "Invalid credentials provided",
  "details": {}
}
```

## Security Best Practices

1. **API Key Security**: Never expose API keys in client-side code or commit to version control
2. **Environment Variables**: Store API keys in secure environment variables
3. **HTTPS Only**: All API calls must use HTTPS
4. **Credential Handling**: Never log or store user credentials in plain text
5. **Organization Scoping**: API keys are scoped to organizations for multi-tenant isolation

## Rate Limits

- Standard rate limiting applies to prevent abuse
- Contact support for higher rate limits if needed
- Authenticated requests have higher limits than unauthenticated

## Support

- **Documentation**: Full API reference available
- **Dashboard**: https://prismai.sh/workspace  
- **Contact**: Support available through dashboard

---

This covers the essential information for integrating with Prism Auth's Authentication-as-a-Service API. For complete documentation including all authentication methods, advanced features, and detailed examples, see the full documentation.