7.3 KiB
Domain Management API
This is a Domain Management API built with Rust (Actix Web) and PostgreSQL. It provides user authentication, domain registration with Discord approval workflow, and invite-based registration limits.
Features
- 🔐 JWT Authentication - Secure user registration and login
- 📝 Domain Registration - Submit domains for approval with usage limits
- 🤖 Discord Integration - Automatic approval workflow via Discord bot
- 📧 Invite System - Users can share registration slots via invite codes
- 🛡️ Rate Limiting - Protection against abuse
- 📊 PostgreSQL Database - Reliable data storage with migrations
Table of Contents
🔒 = Requires authentication
Authentication Endpoints
POST /auth/register
Register a new user account. New users start with 3 domain registrations.
Request:
{
"username": "myusername",
"password": "mypassword"
}
Response:
{
"token": "jwt-token-here",
"user": {
"id": 1,
"username": "myusername",
"registrations_remaining": 3,
"created_at": "2023-01-01T00:00:00Z"
}
}
POST /auth/login
Login with existing credentials.
Request:
{
"username": "myusername",
"password": "mypassword"
}
Response:
{
"token": "jwt-token-here",
"user": {
"id": 1,
"username": "myusername",
"registrations_remaining": 2,
"created_at": "2023-01-01T00:00:00Z"
}
}
GET /auth/me 🔒
Get current user information. Requires Authorization: Bearer <token> header.
Response:
{
"id": 1,
"username": "myusername",
"registrations_remaining": 2,
"created_at": "2023-01-01T00:00:00Z"
}
POST /auth/invite 🔒
Create an invite code that can be redeemed for 3 additional domain registrations. Requires authentication but does NOT consume any of your registrations.
Response:
{
"invite_code": "abc123def456"
}
POST /auth/redeem-invite 🔒
Redeem an invite code to get 3 additional domain registrations. Requires authentication.
Request:
{
"invite_code": "abc123def456"
}
Response:
{
"message": "Invite code redeemed successfully",
"registrations_added": 3
}
GET /auth/domains 🔒
Get all domains owned by the authenticated user, including their status. Requires Authorization: Bearer <token> header.
Query Parameters:
page- Page number (default: 1)limit- Items per page (default: 100, max: 1000)
Response:
{
"domains": [
{
"name": "myawesome",
"tld": "dev",
"ip": "192.168.1.100",
"status": "approved",
"denial_reason": null
},
{
"name": "pending",
"tld": "fr",
"ip": "10.0.0.1",
"status": "pending",
"denial_reason": null
},
{
"name": "rejected",
"tld": "mf",
"ip": "172.16.0.1",
"status": "denied",
"denial_reason": "Invalid IP address"
}
],
"page": 1,
"limit": 100
}
Status Values:
pending- Domain is awaiting approvalapproved- Domain has been approved and is activedenied- Domain was rejected (seedenial_reasonfor details)
Domain Endpoints
GET /
Returns a simple message with the available endpoints and rate limits.
Response:
Hello, world! The available endpoints are:
GET /domains,
GET /domain/{name}/{tld},
POST /domain,
PUT /domain/{key},
DELETE /domain/{key},
GET /tlds.
Ratelimits are as follows: 10 requests per 60s.
POST /domain 🔒
Submit a domain for approval. Requires authentication and consumes one registration slot. The domain will be sent to Discord for manual approval.
Request:
{
"tld": "dev",
"ip": "192.168.1.100",
"name": "myawesome"
}
Error Responses:
401 Unauthorized- Missing or invalid JWT token400 Bad Request- No registrations remaining, invalid domain, or offensive name409 Conflict- Domain already exists
GET /domain/:name/:tld
Fetch an approved domain by name and TLD. Only returns domains with 'approved' status.
Response:
{
"tld": "dev",
"name": "myawesome",
"ip": "192.168.1.100"
}
PUT /domain/:name/:tld 🔒
Update the IP address of your approved domain. You can only update domains you own.
Request:
{
"ip": "10.0.0.50"
}
Response:
{
"ip": "10.0.0.50"
}
DELETE /domain/:name/:tld 🔒
Delete your domain. You can only delete domains you own.
Response:
200 OK- Domain deleted successfully404 Not Found- Domain not found or not owned by you
GET /domains
Fetch all approved domains with pagination support. Only shows domains with 'approved' status.
Query Parameters:
page(orp) - Page number (default: 1)page_size(ors,size,l,limit) - Items per page (default: 15, max: 100)
Response:
{
"domains": [
{
"tld": "dev",
"name": "myawesome",
"ip": "192.168.1.100"
}
],
"page": 1,
"limit": 15
}
GET /tlds
Get the list of allowed top-level domains.
Response:
["mf", "btw", "fr", "yap", "dev", "scam", "zip", "root", "web", "rizz", "habibi", "sigma", "now", "it", "soy", "lol", "uwu", "ohio", "cat"]
POST /domain/check
Check if domain name(s) are available.
Request:
{
"name": "myawesome",
"tld": "dev" // Optional - if omitted, checks all TLDs
}
Response:
[
{
"domain": "myawesome.dev",
"taken": false
}
]
Discord Integration
When a user submits a domain registration, it's automatically sent to a configured Discord channel with:
- 📝 Domain details (name, TLD, IP, user info)
- ✅ Approve button - Marks domain as approved
- ❌ Deny button - Opens modal asking for denial reason
Discord admins can approve or deny registrations directly from Discord.
Configuration
Copy config.template.toml to config.toml and configure your settings.
Rate Limits
- Domain Registration: 5 requests per 10 minutes (per IP)
- General API: No specific limits (yet)
Domain Registration Limits
- User Limit: Each user has a finite number of domain registrations
- Usage: Each domain submission consumes 1 registration from your account
- Replenishment: Use invite codes to get more registrations (3 per invite)
User Registration & Invites
- Registration: Anyone can register - no invite required
- New Users: Start with 3 domain registrations automatically
- Invite Creation: Any authenticated user can create invite codes (no cost)
- Invite Redemption: Redeem invite codes for 3 additional domain registrations
- Invite Usage: Each invite code can only be redeemed once