Domain Whitelisting
Verify company domains and let team members auto-join your organization.
All management endpoints require admin role. Join endpoints are public. Base URL: https://api.airaproof.com/api/v1
Overview
Domain whitelisting lets organizations onboard team members without manual invites. Once a domain is verified, anyone with a matching email can self-register and join the organization automatically.
Add Domain
POST /api/v1/domains
Authorization: Bearer <token>Requires admin role. Initiates domain verification by generating a DNS TXT record.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain to verify (e.g. acme.com) |
Response (201)
{
"id": "uuid",
"domain": "acme.com",
"status": "pending",
"verification_token": "TqI6h2H2XuQG...",
"txt_record": "aira-verify=TqI6h2H2XuQG...",
"verified_at": null,
"created_at": "2026-03-27T10:00:00Z"
}DNS Setup
Add a TXT record to your DNS provider:
| Field | Value |
|---|---|
| Type | TXT |
| Name | @ (or your domain) |
| Content | The txt_record value from the response |
Verify Domain
POST /api/v1/domains/{domain_id}/verify
Authorization: Bearer <token>Checks DNS for the TXT record. On success, the domain is added to the organization's allowed domains list.
Response
{
"id": "uuid",
"domain": "acme.com",
"status": "verified",
"verification_token": "TqI6h2H2XuQG...",
"txt_record": "aira-verify=TqI6h2H2XuQG...",
"verified_at": "2026-03-27T10:05:00Z",
"created_at": "2026-03-27T10:00:00Z"
}DNS propagation can take a few minutes. If verification fails, wait and try again.
List Domains
GET /api/v1/domains
Authorization: Bearer <token>Returns all domains (pending and verified) for the organization.
Response
{
"domains": [
{
"id": "uuid",
"domain": "acme.com",
"status": "verified",
"verification_token": "...",
"txt_record": "aira-verify=...",
"verified_at": "2026-03-27T10:05:00Z",
"created_at": "2026-03-27T10:00:00Z"
}
],
"org_slug": "acme-abc123",
"request_id": "req_abc123"
}Remove Domain
DELETE /api/v1/domains/{domain_id}
Authorization: Bearer <token>Removes the domain from verification and the allowed domains list. Returns 204.
Public Join
These endpoints require no authentication.
Get Join Info
GET /api/v1/join/{org_slug}Returns organization info for the join page.
{
"org_name": "Acme Corp",
"slug": "acme-abc123",
"has_domains": true
}Join by Domain
POST /api/v1/join/{org_slug}Registers a new user into the organization. Email domain must match a verified domain.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Must match a verified domain |
password | string | Yes | Minimum 8 characters |
Response (201)
{
"token": "eyJ...",
"expires_in": 86400,
"org_uuid": "uuid",
"user_uuid": "uuid"
}Errors
| Status | Code | Description |
|---|---|---|
| 403 | DOMAIN_FORBIDDEN | Email domain not in allowed list |
| 404 | NOT_FOUND | Organization not found |
| 409 | DUPLICATE_USER | Email already registered |
Auto-Join on Registration
When a user registers (email or OAuth) with an email matching a verified domain, they are automatically moved to that organization as a member. No invite needed.
This works with:
- Email/password registration
- Google OAuth
- GitHub OAuth
- GitLab OAuth