# Auth

## Create authentication token

 - [POST /auth/token](https://docs.pers.ninja/swagger/auth/authcontroller_createtoken.md): Universal token creation with consistent token-in-body pattern.

## Authentication Flows

### USER AUTHENTICATION
- Header: x-project-key (tenant identification)
- Body: { authToken: "jwt_from_provider", authType: "user" }
- Returns: User session with PERS JWT tokens

### BUSINESS AUTHENTICATION
- Header: x-project-key (tenant identification)
- Body: { authToken: "jwt_from_provider", authType: "business", context: { businessId: "uuid" } }
- Returns: Business session with PERS JWT tokens (includes role in JWT)
- If user has single business membership, context.businessId is auto-selected
- If user has multiple memberships without context.businessId, returns MULTIPLE_CONTEXT_SELECTION_REQUIRED error with available options

### ADMIN AUTHENTICATION
- Header: x-project-key (tenant identification)
- Body: { authToken: "firebase_jwt", authType: "tenant" }
- Returns: Admin session with PERS JWT tokens

---

## Third-Party JWT Requirements

When providing authToken from an external identity provider, the JWT must meet these requirements:

### JWT Header
| Field | Required | Description |
|-------|----------|-------------|
| kid | Yes | Key ID matching a key in your JWKS |
| alg | Yes | Signing algorithm (RS256, ES256, EdDSA) |

### JWT Payload Claims
| Claim | Required | Description |
|-------|----------|-------------|
| iss | Yes | Issuer URL (used for JWKS discovery) |
| sub | Yes | Subject identifier (user ID) |
| aud | Yes | Audience (your registered client ID) |
| exp | Yes | Expiration timestamp (Unix epoch) |
| iat | Yes | Issued at timestamp (Unix epoch) |

### Provider Requirements
Your identity provider must expose public keys via one of:
1. {issuer}/.well-known/jwks.json (JWKS endpoint)
2. {issuer}/.well-known/openid-configuration (OIDC discovery with jwks_uri)

### Verification Flow
1. PERS extracts iss claim from JWT
2. Fetches JWKS from {issuer}/.well-known/jwks.json
3. Matches kid header to find signing public key
4. Verifies signature using matched key
5. Validates exp, iat, aud claims
6. Issues PERS access/refresh tokens on success

### PERS JWKS (For verifying our tokens)
- JWKS: https://api.pers.ninja/.well-known/jwks.json
- Discovery: https://api.pers.ninja/.well-known/openid-configuration

## Refresh authentication tokens

 - [POST /auth/refresh](https://docs.pers.ninja/swagger/auth/authcontroller_refresh.md): Refresh access tokens using valid refresh token

## Verify JWT token

 - [POST /auth/verify](https://docs.pers.ninja/swagger/auth/authcontroller_verifytoken.md): Verify JWT tokens with automatic issuer detection:
        
        - Decodes JWT to extract issuer claim
        - PERS tokens: Verified internally
        - External tokens: Future support planned
        - Standards-compliant JWT verification

## Send magic link email

 - [POST /auth/magic-link/send](https://docs.pers.ninja/swagger/auth/authcontroller_sendmagiclink.md): Send a magic link email for passwordless authentication. Rate limited to 3 requests per email per 10 minutes.