> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cisisk.projects.bernardopinto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth

> Login, register, logout, and refresh token

## Login

Authenticate and receive JWT tokens.

```
POST /api/v1/auth/login
```

| Field    | Type   | Required |
| -------- | ------ | -------- |
| username | string | yes      |
| password | string | yes      |

```json theme={null}
{
  "username": "admin",
  "password": "secret123"
}
```

```json theme={null}
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "Admin",
      "last_name": "User",
      "username": "admin",
      "email": "admin@example.com",
      "phone": null,
      "lang": "en",
      "location": null,
      "nationality": null,
      "timezone": "UTC",
      "last_uuid": null,
      "last_login_ip": "::1",
      "last_login_at": "2026-06-28T12:00:00.000Z",
      "last_logout_ip": null,
      "is_active": true,
      "created_at": "2026-06-28T12:00:00.000Z",
      "created_by": null,
      "updated_at": "2026-06-28T12:00:00.000Z",
      "created_ip": "::1",
      "updated_ip": "::1"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  },
  "metadata": {}
}
```

***

## Register

Create a new user account. Requires `PUBLIC_REGISTER=true` or admin token.

```
POST /api/v1/auth/register
```

| Field       | Type   | Required | Default |
| ----------- | ------ | -------- | ------- |
| first\_name | string | yes      | —       |
| last\_name  | string | yes      | —       |
| username    | string | yes      | —       |
| email       | string | yes      | —       |
| password    | string | yes      | —       |
| phone       | string | no       | `null`  |
| lang        | string | no       | `"en"`  |
| location    | string | no       | `null`  |
| nationality | string | no       | `null`  |
| timezone    | string | no       | `"UTC"` |

```json theme={null}
{
  "first_name": "John",
  "last_name": "Doe",
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securePass123",
  "phone": "+351912345678",
  "lang": "en",
  "location": "Lisbon",
  "nationality": "Portuguese",
  "timezone": "Europe/Lisbon"
}
```

```json theme={null}
{
  "success": true,
  "message": "Registration successful",
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "phone": "+351912345678",
    "lang": "en",
    "location": "Lisbon",
    "nationality": "Portuguese",
    "timezone": "Europe/Lisbon",
    "last_uuid": null,
    "last_login_ip": null,
    "last_login_at": null,
    "last_logout_ip": null,
    "is_active": true,
    "created_at": "2026-06-28T12:00:00.000Z",
    "created_by": null,
    "updated_at": "2026-06-28T12:00:00.000Z",
    "created_ip": "::1",
    "updated_ip": "::1"
  },
  "metadata": {}
}
```

***

## Logout

Revoke refresh token(s). Requires Bearer token.

```
POST /api/v1/auth/logout
Authorization: Bearer <token>
```

| Field          | Type   | Required                    |
| -------------- | ------ | --------------------------- |
| refresh\_token | string | no (revokes all if omitted) |

```json theme={null}
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

```json theme={null}
{
  "success": true,
  "message": "Logout successful",
  "data": null,
  "metadata": {}
}
```

***

## Refresh

Exchange a refresh token for a new token pair. The old token is revoked.

```
POST /api/v1/auth/refresh
```

| Field          | Type   | Required |
| -------------- | ------ | -------- |
| refresh\_token | string | yes      |

```json theme={null}
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

```json theme={null}
{
  "success": true,
  "message": "Token refreshed",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  },
  "metadata": {}
}
```