Domains

Domains represent each instance's URLs and DNS setup.

List all instance domains

Use this endpoint to get a list of all domains for an instance. The response will contain the primary domain for the instance and any satellite domains. Each domain in the response contains information about the URLs where Clerk operates and the required CNAME targets.

SecuritybearerAuth
Responses
200

A list of domains

get/domains
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Add a domain

Add a new domain for your instance. Useful in the case of multi-domain instances, allows adding satellite domains to an instance. The new domain must have a name. The domain name can contain the port for development instances, like localhost:3000. At the moment, instances can have only one primary domain, so the is_satellite parameter must be set to true. If you're planning to configure the new satellite domain to run behind a proxy, pass the proxy_url parameter accordingly.

SecuritybearerAuth
Request
Request Body schema: application/json
name
required
string

The new domain name. Can contain the port for development instances.

is_satellite
required
boolean

Marks the new domain as satellite. Only true is accepted at the moment.

Value: true
proxy_url
string

The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances.

Responses
200

A domain

400

Request was not successful

402

Request was not successful

422

Invalid request parameters

post/domains
Request samples
application/json
{
  • "name": "string",
  • "is_satellite": true,
  • "proxy_url": "string"
}
Response samples
application/json
{
  • "object": "domain",
  • "id": "string",
  • "name": "string",
  • "is_satellite": true,
  • "frontend_api_url": "string",
  • "accounts_portal_url": "string",
  • "proxy_url": "string",
  • "development_origin": "string",
  • "cname_targets": [
    ]
}

Delete a satellite domain

Deletes a satellite domain for the instance. It is currently not possible to delete the instance's primary domain.

SecuritybearerAuth
Request
path Parameters
domain_id
required
string

The ID of the domain that will be deleted. Must be a satellite domain.

Responses
200

Deleted Object

403

Request was not successful

404

Resource not found

delete/domains/{domain_id}
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "slug": "string",
  • "deleted": true
}

Update a domain

The proxy_url can be updated only for production instances. Update one of the instance's domains. Both primary and satellite domains can be updated. If you choose to use Clerk via proxy, use this endpoint to specify the proxy_url. Whenever you decide you'd rather switch to DNS setup for Clerk, simply set proxy_url to null for the domain. When you update a production instance's primary domain name, you have to make sure that you've completed all the necessary setup steps for DNS and emails to work. Expect downtime otherwise. Updating a primary domain's name will also update the instance's home origin, affecting the default application paths.

SecuritybearerAuth
Request
path Parameters
domain_id
required
string

The ID of the domain that will be updated.

Request Body schema: application/json
required
name
string or null

The new domain name. For development instances, can contain the port, i.e myhostname:3000. For production instances, must be a valid FQDN, i.e mysite.com. Cannot contain protocol scheme.

proxy_url
string or null

The full URL of the proxy that will forward requests to Clerk's Frontend API. Can only be updated for production instances.

is_secondary
boolean or null

Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and will be stored as part of the domain. This is useful for supporting multiple apps (one primary and multiple secondaries) on the same root domain (eTLD+1).

Responses
200

A domain

400

Request was not successful

404

Resource not found

422

Invalid request parameters

patch/domains/{domain_id}
Request samples
application/json
{
  • "name": "string",
  • "proxy_url": "string",
  • "is_secondary": true
}
Response samples
application/json
{
  • "object": "domain",
  • "id": "string",
  • "name": "string",
  • "is_satellite": true,
  • "frontend_api_url": "string",
  • "accounts_portal_url": "string",
  • "proxy_url": "string",
  • "development_origin": "string",
  • "cname_targets": [
    ]
}