# Zapini API — Authentication

**Version:** 1.2.0
**Base URL:** `https://zapini.app/api/v1`

---

## Authentication

The API supports two methods:

### 1. User Tokens (Sanctum)
After logging in via `/auth/login`, you receive a user token for full platform access.

### 2. Instance API Tokens (Recommended for Integrations)
Generate API tokens (`sk_` prefix) for specific WhatsApp instances. These tokens:
- Don't require user login
- Are scoped to a single instance
- Can be revoked independently
- Work with all API endpoints

### Required Headers

```
Authorization: Bearer {your_token}
Accept: application/json
Content-Type: application/json
```

---

## POST /auth/login

Authenticate and receive an access token.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email |
| password | string | Yes | User password |
| device_name | string | No | Device name |

**Example Request:**

```bash
curl -X POST https://zapini.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password",
    "device_name": "My App"
  }'
```

**Success Response:**

```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "name": "User",
      "email": "user@example.com",
      "role": "admin",
      "locale": "en",
      "tenant": {
        "id": 1,
        "name": "My Company",
        "status": "active"
      }
    },
    "token": "1|abc123xyz...",
    "token_type": "Bearer",
    "expires_at": null
  }
}
```

**2FA Required Response:**

```json
{
  "success": true,
  "two_factor_required": true,
  "message": "Two-factor verification required"
}
```

---

## POST /auth/two-factor

Complete login with 2FA code.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email |
| password | string | Yes | User password |
| code | string | Yes | 2FA code (6 digits) |
| device_name | string | No | Device name |

---

## POST /auth/register

Register a new user.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Full name |
| email | string | Yes | Email (unique) |
| password | string | Yes | Password (min 8 characters) |
| password_confirmation | string | Yes | Password confirmation |
| device_name | string | No | Device name |
| terms_accepted | boolean | Yes | Terms acceptance |

---

## GET /auth/me

Returns authenticated user data.

**Headers:** Requires authentication

**Response:**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "User",
      "email": "user@example.com",
      "role": "admin",
      "locale": "en",
      "timezone": "America/New_York",
      "email_verified": true,
      "two_factor_enabled": false,
      "tenant": {
        "id": 1,
        "name": "My Company",
        "status": "active"
      }
    }
  }
}
```

---

## PATCH /auth/me

Update user profile.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | No | New name |
| locale | string | No | Language (en, pt-BR, es) |
| timezone | string | No | Timezone |

---

## POST /auth/logout

End current session (revoke token).

---

## POST /auth/logout-all

End all sessions (revoke all tokens).

---

## POST /auth/refresh

Refresh the access token.

**Response:**

```json
{
  "success": true,
  "message": "Token refreshed",
  "data": {
    "token": "2|new_token...",
    "token_type": "Bearer",
    "expires_at": null
  }
}
```

---

## POST /auth/password/forgot

Send password recovery email.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email |

---

## POST /auth/password/reset

Reset password with recovery token.

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| token | string | Yes | Recovery token |
| email | string | Yes | User email |
| password | string | Yes | New password |
| password_confirmation | string | Yes | Confirmation |

---

## POST /auth/password/change

Change password (authenticated user).

**Parameters:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| current_password | string | Yes | Current password |
| password | string | Yes | New password |
| password_confirmation | string | Yes | Confirmation |

---

## GET /auth/sessions

List all active user sessions.

**Response:**

```json
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "name": "Chrome - Windows",
        "last_used_at": "2025-01-15T10:30:00Z",
        "created_at": "2025-01-10T08:00:00Z",
        "is_current": true
      }
    ]
  }
}
```

---

## DELETE /auth/sessions/{id}

Revoke a specific session.

---

*Generated by Zapini — https://zapini.app*