# Authelia API - Postman Collection

This directory contains Postman files for testing and interacting with the Authelia API.

## Files

- `authelia-api.postman_collection.json` - Main Postman collection with all API endpoints
- `authelia-api.postman_environment.json` - Environment variables for easy configuration
- `src/test_bulk.json` - Example request body for bulk user creation

## Setup Instructions

### 1. Import into Postman

1. Open Postman
2. Click **Import** button
3. Select both the collection and environment files
4. Click **Import**

### 2. Configure Environment

1. In Postman, select the **"Authelia API"** environment from the environment dropdown (top-right)
2. Click the eye icon next to the environment name
3. Set the following variables:

| Variable | Value | Description |
|----------|-------|-------------|
| `base_url` | `http://127.0.0.1:8080` | API base URL (default) |
| `bearer_token` | Your session.secret | **Required** - Get from Authelia config |

### 3. Get Your Bearer Token

The initial bearer token is your Authelia `session.secret`:

```bash
# Extract from Authelia configuration
grep -A2 "session:" /opt/authelia/configuration.yml | grep "secret:" | awk '{print $2}'
```

Example token: `5DdUKe12k6niaaekpTeB0H35A48xmTWBWJcI3AOoqPA=`

**Security Note:** This token provides full API access. Keep it secure!

## API Endpoints

### Health Check
- **GET** `/api/health`
- No authentication required
- Returns API status and version

### Bulk Create Users
- **POST** `/api/users/bulk`
- Requires Bearer token
- Creates multiple users with auto-generated passwords
- Example request body in `src/test_bulk.json`

### List Users
- **GET** `/api/users`
- Requires Bearer token
- Lists all users in the system

### Delete User
- **DELETE** `/api/users/{username}`
- Requires Bearer token
- Deletes a user by username

## Testing Workflow

1. **Health Check**: Verify API is running
2. **Bulk Create**: Add test users (see example below)
3. **List Users**: Confirm users were created
4. **Delete User**: Clean up test users

### Example: Create Test Users

Use the pre-configured request in the collection, or modify the body:

```json
{
  "users": [
    {
      "username": "test.user1",
      "display_name": "Test User One",
      "email": "test1@example.com",
      "groups": ["users", "developers"]
    },
    {
      "username": "test.user2",
      "display_name": "Test User Two",
      "email": "test2@example.com",
      "groups": ["users"]
    }
  ]
}
```

## Response Examples

### Health Check
```json
{
  "status": "ok",
  "version": "dev",
  "time": "2026-04-02T00:00:00Z"
}
```

### Bulk Create Success
```json
{
  "success": true,
  "created": 2,
  "users": [
    {
      "username": "john.doe",
      "display_name": "John Doe",
      "email": "john.doe@example.com",
      "placeholder_password": "aB3$fG7!kL9*mN2@pQ",
      "status": "created"
    }
  ]
}
```

### List Users
```json
[
  {
    "username": "john.doe",
    "display_name": "John Doe",
    "email": "john.doe@example.com",
    "groups": ["users", "admins"],
    "disabled": false,
    "created_at": "2026-04-02 00:00:00",
    "updated_at": "2026-04-02 00:00:00"
  }
]
```

## Troubleshooting

### 401 Unauthorized
- Check that `bearer_token` is set in environment
- Verify token matches Authelia `session.secret`
- Ensure `Authorization` header is present

### Connection Refused
- Verify Authelia API is running: `systemctl status authelia-api`
- Check API port: Default is `127.0.0.1:8080`
- Ensure firewall allows local connections

### 400 Bad Request
- Validate JSON request body format
- Check required fields: `username`, `display_name`, `email`
- Ensure email contains '@' symbol

## Next Steps

1. Test API with actual user data
2. Configure SMTP for email onboarding (if needed)
3. Set up monitoring/alerting for API health
4. Consider rotating bearer tokens for production

## Related Resources

- [Authelia API Source Code](../src/)
- [Installation Guide](README.md)
- [Authelia Documentation](https://www.authelia.com/)