Create a project domain

Attach a new domain to a project.

Project domains are used by DevPayr to validate runtime license usage when a license is configured to validate against project domains (validate_against = project_domains).

Endpoint

POST /project/{project}/domains

Full URL:

https://api.devpayr.dev/api/v1/project/{project}/domains

Authentication

✅ Required: API Key

Send your API key using:

X-API-KEY: <your_api_key>

Path Parameters

Parameter	Type	Required	Description
project	integer	Yes	The ID of the project to attach the domain to.

Authorization Rules

DevPayr enforces domain creation permissions in two layers:

1) API key access to the project

• Project-scoped API keys may only manage the project they are scoped to.

• Global API keys may only manage projects owned by the same user.

If this fails, DevPayr may return:

Project-scoped mismatch:

{ "message": "This API key is not allowed to manage this project." }

Global key but not owner:

{ "message": "This API key does not have permission to manage this project." }

2) Plan-based domain limit

Your subscription plan may limit how many domains a project can have.

If you have reached your plan limit, DevPayr rejects the request.

Error (403)

{ "message": "You are not allowed to add more domains to this project." }

Request Body

Send a JSON request body.

Fields

Field	Type	Required	Description
domain	string	✅	The domain value (must match DevPayr’s supported domain format).
environment	string	✅	One of: production, staging, development.
is_primary	boolean	No	If true, DevPayr demotes any existing primary domain and makes this one primary.
is_verified	boolean	No	Optional verification flag. Default false.
is_locked	boolean	No	Optional lock flag. Default false.
has_paid	boolean	No	Optional payment flag. Default false.
is_active	boolean	No	Whether the domain is active. Default true.

Domain Format Rules

The domain field supports common runtime environments, including:

• Standard domains:

  • app.example.com

  • example.com

• Localhost with optional port:

  • localhost

  • localhost:8000

• IPv4 with optional port:

  • 127.0.0.1

  • 192.168.1.20:3000

• IPv6 in brackets with optional port:

  • [::1]:3000

If the domain format is invalid, validation fails with:

{ "message": "The domain format is invalid. Examples: app.example.com, localhost:8000, 127.0.0.1, [::1]:3000." }

Uniqueness Rules

A domain must be unique within the same project.

If the domain already exists on the project, validation fails with:

{ "message": "This domain has already been added to this project." }

Example Request

curl -X POST "https://api.devpayr.dev/api/v1/project/2/domains" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "domain": "dev.example.com",
    "environment": "production",
    "is_primary": false
  }'

Response

Success (201)

On success, DevPayr returns the newly created domain record and excludes internal fields such as user_id.

Example Response

{
  "status": "success",
  "message": "Domain added successfully.",
  "data": {
    "domain": "dev.example.com",
    "environment": "production",
    "is_primary": false,
    "is_verified": false,
    "is_locked": false,
    "has_paid": false,
    "is_active": true,
    "project_id": 2,
    "updated_at": "2025-12-13T12:02:47.000000Z",
    "created_at": "2025-12-13T12:02:47.000000Z",
    "id": 1
  },
  "errors": null
}

Special Behavior: Primary Domain Demotion

If is_primary is set to true:

• DevPayr automatically sets every other domain on the project to is_primary = false

• the new domain becomes the only primary domain for the project

This guarantees that each project has at most one primary domain.

Validation Errors (422)

Validation failures return a 422 response (with field-level errors).

Common cases:

• missing domain

• invalid domain format

• domain already exists on the project

• missing or invalid environment

• boolean fields not boolean

Notable custom messages include:

Missing domain:

{ "message": "Please enter a domain." }

Invalid domain format:

{ "message": "The domain format is invalid. Examples: app.example.com, localhost:8000, 127.0.0.1, [::1]:3000." }

Duplicate domain:

{ "message": "This domain has already been added to this project." }

Errors

Missing API Key (401)

{ "message": "Missing required X-API-KEY header." }

Invalid / Expired API Key (403)

{ "message": "Invalid or expired API key." }

Unauthorized (403)

Plan limit or not allowed:

{ "message": "You are not allowed to add more domains to this project." }

Project-scoped mismatch:

{ "message": "This API key is not allowed to manage this project." }

Global key not owner:

{ "message": "This API key does not have permission to manage this project." }

Project Not Found (404)

{ "message": "Resource not found." }

Rate Limited (429)

{ "message": "Rate limit exceeded (X requests/min). Please slow down." }