# Route Spec

## Route ID
`auth-logout`

## Endpoint
`POST /api/v1/auth/logout`

## Human Description
Logs out the current device session by revoking the submitted refresh token.

## Authentication
- Required: `yes`
- Auth type: `bearer + refresh token`
- Required roles/scopes: `authenticated user`

## Request
### Headers
- `Content-Type: application/json`
- `Authorization: Bearer <accessToken>`

### Body
```json
{
  "refreshToken": "jwt_refresh_token",
  "logoutFromAllDevices": false
}
```

## Responses
### Success: `200 OK`
When returned:
- Session revoked successfully.

Body:
```json
{
  "success": true,
  "message": "Logged out successfully",
  "data": {}
}
```

### Error: `401 Unauthorized`
When returned:
- Access token invalid or refresh token not owned by user.

Body:
```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "details": {}
  }
}
```

## Data & Caching Dependencies
- **Spanner Tables:** `None`
- **Redis Cache:** `refresh_tokens (Read/Delete)`
- **GCS Storage:** `None`
- **Edge Cache (CDN):** `No`

## Side Effects
- Revokes one or all refresh tokens based on flag.