168 lines
4 KiB
Markdown
168 lines
4 KiB
Markdown
# 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/)
|