# Auth API

Authentication and identity management including OAuth 2.0 flows, session management, password reset, and multi-factor authentication. Supports multiple grant types for different application scenarios.

Authentication and identity management including OAuth 2.0 flows, session management, password reset, and multi-factor authentication. Supports multiple grant types for different application scenarios.

## Available Endpoints

| Method | Endpoint                                             | Description                    |
| ------ | ---------------------------------------------------- | ------------------------------ |
| `POST` | [`/api/auth/identify`](#post-apiauthidentify)        | Identify authentication method |
| `GET`  | [`/api/auth/sso/discover`](#get-apiauthssodiscover)  | Discover SSO for domain        |
| `POST` | [`/api/auth/sso/complete`](#post-apiauthssocomplete) | Complete SSO authentication    |

## Endpoints

### POST /api/auth/identify

Identify authentication method

Determine the best authentication method for an email address (SSO, password, magic link).

**Auth:** none

#### Body parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `email` | string | yes | Email address to identify authentication method | `user@example.com` |

#### Request example

**curl**

```bash
curl -X POST "https://api.indexhog.com/api/auth/identify" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"email":"user@example.com"}'
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/identify", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "email": "user@example.com"
}),
});

const data = await response.json();
console.log(data);
```

#### Response `200` — Authentication method identified

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "method": "password",
  "ssoProvider": "okta",
  "ssoRedirectUrl": "string",
  "hasPasskey": false,
  "allowMagicLink": true
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### GET /api/auth/sso/discover

Discover SSO for domain

Find organization SSO configuration by email domain.

**Auth:** none

#### Query parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `domain` | string | yes | Email domain to check for SSO configuration | `acme.com` |

#### Request example

**curl**

```bash
curl -X GET "https://api.indexhog.com/api/auth/sso/discover" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/sso/discover", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);
```

#### Response `200` — SSO discovery result

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "organizationSlug": "acme-corp",
  "organizationName": "Acme Corporation",
  "ssoProvider": "okta",
  "loginUrl": "https://api.indexhog.com/auth/sso/acme-corp/login"
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### POST /api/auth/sso/complete

Complete SSO authentication

Exchange an SSO token for an authenticated session.

**Auth:** none

#### Body parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `handle` | string | yes | Opaque single-use handle issued by /api/auth/sso/callback. Exchanged server-side for the signed completion token; the token itself is never exposed to the browser. |  |

#### Request example

**curl**

```bash
curl -X POST "https://api.indexhog.com/api/auth/sso/complete" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"handle":"string"}'
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/auth/sso/complete", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "handle": "string"
}),
});

const data = await response.json();
console.log(data);
```

#### Response `200` — SSO authentication completed

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "userId": "507f1f77bcf86cd799439011",
  "email": "user@acme.com"
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```