Proxy API_
Point custom domains at a customer's Appwrite project API, functions, and sites with the Proxy API, then verify them over DNS.
4 min read
The Proxy API attaches a custom domain to a resource inside one Appwrite project. A rule maps one hostname to one target, and the target is the project API, a function, a site, or a redirect to another URL.
Partner platforms use the Proxy API to give each customer a branded hostname. When a customer sets api.customer.com in your product, your backend creates a rule on that customer's project and reports the verification state back to your UI.
Authentication
Proxy rules belong to a project, not to an organization. Authenticate with the customer's project ID and a project API key. A Partners key cannot read or write proxy rules.
| Scope | Operations |
|---|---|
rules.read | List rules, get a rule |
rules.write | Create a rule, verify a rule, delete a rule |
proxy.invalidations.write | Invalidate cached responses |
Rule types
Each create operation produces a rule with a fixed type. The type field tells you what the hostname resolves to.
| Operation | type | Target |
|---|---|---|
createAPIRule | api | The project's Appwrite API |
createFunctionRule | deployment | A function in the project |
createSiteRule | deployment | A site in the project |
createRedirectRule | redirect | Another URL, with a status code |
Appwrite derives the rule ID from the domain. A second rule for the same hostname fails with 409 rule_already_exists, so your provisioning code can treat that error as "already configured" instead of a fatal failure.
API rules
An API rule points a hostname at the project's Appwrite API, so customer apps call api.customer.com instead of the regional Appwrite endpoint.
Function and site rules
Function and site rules both take an optional branch. With a branch set, Appwrite moves the rule to the newest deployment from that branch.
Both rules come back with type set to deployment. deploymentResourceType holds function or site and tells them apart.
Redirect rules
A redirect rule sends traffic to another URL. resourceType accepts function or site, and resourceId names the resource the redirect belongs to. statusCode accepts 301, 302, 307, and 308.
Verification
A new rule starts at unverified. Appwrite checks DNS only when the verify operation runs, so the customer has to publish the record first. The sequence is:
- The rule is created, and your backend stores its
$id. - The customer adds a CNAME record for the hostname. The record value depends on the rule type and the deployment, and the domain's verification panel in the Console shows it.
- The verify operation runs. Appwrite resolves the hostname and issues a certificate.
Some DNS providers reject a CNAME record on an apex domain. If the customer's provider rejects one, the customer can delegate the zone to the Appwrite nameservers instead.
If the CNAME record is missing, the call fails and the message names the hostname and the resolver that ran the lookup. The rule also keeps the last failure in its logs field, so your UI can show the reason without repeating the call.
You can retry verification after the customer fixes DNS, because the check is idempotent.
Reading rules
Rule deletion
Deleting a rule stops Appwrite from serving the hostname. The customer's DNS record survives the delete and has to be removed separately.
Invalidations
Appwrite caches responses served through a verified domain, and an invalidation clears that cache for one domain. The domain must be verified first, because an unverified domain has nothing cached.
type | reference holds |
|---|---|
all | Nothing. Clears every cached response for the domain |
path | A path to clear |
tag | A cache tag name |
Rule fields
| Field | Description |
|---|---|
$id | Rule ID, derived from the domain |
domain | The hostname the rule serves |
type | api, deployment, or redirect |
trigger | manual for rules you create, deployment for rules Appwrite creates |
status | unverified, verifying, or verified |
logs | The last verification message, empty until a check runs |
deploymentResourceType | function or site on deployment rules, empty otherwise |
deploymentResourceId | The function ID or site ID on deployment rules |
deploymentVcsProviderBranch | The branch whose deployments the rule follows, empty when unset |
redirectUrl | The target URL on redirect rules |
redirectStatusCode | The HTTP status code on redirect rules |
renewAt | When Appwrite renews the certificate |
Related
Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.