# SPECIFICATIONS/06_API/06_01_AUTH_ENDPOINTS.md

**PURPOSE:** Specifies the authentication and role management API surface. This file defines exactly what the HTTP contract looks like for Auth and RBAC.

> **Security constraints (rate limiting, token handling):** `../../CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Security Mandates
> **Permission names by endpoint:** `06_08_ERROR_CODES.md` → Error Catalog

---

## POST /api/v1/auth/login

**Auth:** Public (no token required)

**Inputs:**

| Field | Type | Required | Validation |
|:---|:---|:---|:---|
| `email` | string | Yes | email format |
| `password` | string | Yes | — |

**Outputs:**
```json
{
    "success": true,
    "message": "string",
    "data": {
        "token": "string",
        "token_type": "Bearer",
        "admin": {
            "id": 1,
            "name": "string",
            "email": "string"
        }
    }
}
```

**Behavior:**
- Validates credentials against stored bcrypt hash
- Returns bearer token on success
- Hard deletes token on subsequent logout

**Errors:**

| Condition | Key | HTTP |
|:---|::---|:---|
| Invalid credentials | `errors/auth.invalid_token` | 401 |
| Rate limit exceeded | `errors/auth.too_many_attempts` | 429 |

---

## DELETE /api/v1/auth/logout

**Auth:** Required

**Inputs:** None (token from header)

**Outputs:**
```json
{
    "success": true,
    "message": "string"
}
```

**Behavior:**
- Hard deletes the current token from the database (not soft delete)

---

## GET /api/v1/auth/me

**Auth:** Required

**Inputs:** None

**Outputs:**
```json
{
    "success": true,
    "message": "string",
    "data": {
        "id": 1,
        "name": "string",
        "email": "string",
        "created_at": "timestamp",
        "roles": [],
        "permissions": []
    }
}
```

**Behavior:**
- Returns the authenticated admin's profile including assigned roles and permissions from Spatie

---

## POST /api/v1/roles

**Auth:** Required
**Permission:** `roles.create`

**Inputs:**

| Field | Type | Required | Validation |
|:---|:---|:---|:---|
| `name` | string | Yes | unique |
| `permissions` | array | Yes | array of permission strings |

**Outputs:**
```json
{
    "success": true,
    "message": "string",
    "data": {
        "id": 1,
        "name": "string",
        "permissions": ["string"]
    }
}
```

**Behavior:**
- Creates role and attaches all specified permissions in a single atomic operation