> ## Documentation Index
> Fetch the complete documentation index at: https://mako-docs.devinagiffy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Hitler API

## Overview

The Hitler API uses JWT (JSON Web Tokens) for authentication. There are two ways to obtain a token:

1. **Email/Password** - Traditional login
2. **Slack OAuth** - Sign in with Slack

## Email/Password Authentication

### Login

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.hitler.app/api/auth/login" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "user@example.com",
      "password": "your-password"
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.hitler.app/api/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "user@example.com",
      password: "your-password",
    }),
  });

  const { accessToken, user } = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 604800,
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "employee",
    "organizationId": "org-uuid"
  }
}
```

### Register

```bash theme={null}
curl -X POST "https://api.hitler.app/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure-password-123",
    "name": "Jane Smith",
    "organizationId": "org-uuid"
  }'
```

<Note>
  Registration requires a valid `organizationId`. Organizations are created separately or via Slack
  OAuth.
</Note>

## Slack OAuth

### Flow Overview

```
1. Frontend requests OAuth URL
2. User redirected to Slack
3. User authorizes
4. Slack redirects to callback
5. API exchanges code for tokens
6. JWT returned to frontend
```

### Get OAuth URL

```bash theme={null}
curl "https://api.hitler.app/api/auth/slack/url?returnUrl=https://app.hitler.app"
```

**Response:**

```json theme={null}
{
  "url": "https://slack.com/oauth/v2/authorize?client_id=...",
  "state": "random-state-string",
  "callbackUrl": "https://api.hitler.app/api/auth/slack/callback",
  "type": "signin"
}
```

### Callback

The callback is handled automatically. On success, the user is redirected to `returnUrl` with the token.

## Using the Token

Include the token in the `Authorization` header:

```bash theme={null}
curl "https://api.hitler.app/api/auth/me" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

## Token Refresh

Tokens expire after 7 days. Refresh before expiry:

```bash theme={null}
curl -X POST "https://api.hitler.app/api/auth/refresh" \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"
```

**Response:**

```json theme={null}
{
  "accessToken": "new-jwt-token...",
  "expiresIn": 604800,
  "user": { ... }
}
```

## Get Current User

Verify a token and get user info:

```bash theme={null}
curl "https://api.hitler.app/api/auth/me" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**

```json theme={null}
{
  "id": "user-uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "employee",
  "organizationId": "org-uuid"
}
```

## Token Structure

The JWT payload contains:

```json theme={null}
{
  "sub": "user-uuid",
  "orgId": "organization-uuid",
  "role": "employee",
  "iat": 1642089600,
  "exp": 1642694400
}
```

| Field   | Description                          |
| ------- | ------------------------------------ |
| `sub`   | User ID                              |
| `orgId` | Organization ID                      |
| `role`  | User role (employee, manager, admin) |
| `iat`   | Issued at timestamp                  |
| `exp`   | Expiration timestamp                 |

## Error Responses

### Invalid Credentials

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid credentials",
  "error": "Unauthorized"
}
```

### Token Expired

```json theme={null}
{
  "statusCode": 401,
  "message": "Token expired",
  "error": "Unauthorized"
}
```

### Email Already Registered

```json theme={null}
{
  "statusCode": 409,
  "message": "Email already registered",
  "error": "Conflict"
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store tokens securely">
    In browsers, use `httpOnly` cookies or secure storage. Never expose tokens in URLs or logs.
  </Accordion>

  <Accordion title="Refresh before expiry">
    Implement proactive token refresh to avoid interruptions.
  </Accordion>

  <Accordion title="Handle token errors">
    When you receive a 401, redirect to login or attempt refresh.
  </Accordion>

  <Accordion title="Use HTTPS">
    Always use HTTPS in production to protect tokens in transit.
  </Accordion>
</AccordionGroup>