Access control
Access is a setting on the distribution. Changing it applies to the live site immediately. It does not create a deployment.
Modes
| Stored mode | What visitors see |
|---|---|
public | The site, with no gate |
login | A sign-in page. Methods are password, deca, email_code, and email_link |
password | A previous way of writing the password gate. New writes store login instead |
Sending "mode": "password" stores "mode": "login" and "methods": ["password"]. require_mfa cannot be set while password is the only method. The error code is ACCESS_MFA_WITH_PASSWORD.
session_ttl is 1h through 24h. The default is 8h.
Rules
Rules say who may sign in later. They do not apply to the shared password.
| Kind | Value |
|---|---|
email | One address |
email_domain | A domain, with or without a leading @ |
any_signed_in | Any signed-in visitor. Value is empty |
deca_member | A person signed in with a DECA account in this organization. Value is empty. roles and namespaces are optional; leave both empty to allow every member. A person from another organization does not match. Repeat --role and --namespace on edge access rules add, or send roles and namespaces arrays on the API. |
applies_to is live, preview, or both.
A distribution holds 200 rules. A workspace holds 500. Going past either returns ACCESS_RULE_LIMIT.
Network rules
Network rules decide which networks can reach a distribution, before sign-in. They are separate from the access rules above and apply to every visitor, signed in or not. For the steps, see Restrict access by IP address or country.
| Kind | Value |
|---|---|
ip_allow | An IPv4 or IPv6 address or range: 203.0.113.0/24, 2001:db8:1::/48. A bare address is /32 or /128 |
ip_block | The same |
country_allow | An ISO 3166-1 alpha-2 code such as JP |
country_block | The same |
A rule belongs to one distribution, or to the workspace when it is created without one. A distribution uses its own rules and the workspace's together. applies_to is live, preview, or both; the default is both. note is optional text up to 200 characters.
A range with host bits set (10.1.2.3/8) and an allow or block range wider than /8 (IPv4) or /16 (IPv6) are refused, because they are almost always a mistake.
Evaluation order
Edge checks a request in this order and stops at the first match:
- The address is in a blocked range: 403.
- The address is in an allowed range: let in, and country rules are skipped.
- The country is blocked: 403.
- An IP allow list exists and the address is not in it: not allowed.
- A country allow list exists and the country is not in it: not allowed.
- The country is allowed: let in.
- No rule applies: let in.
A visitor whose country Edge cannot tell matches no country rule. "Not allowed" means 403, except under login_fallback (below). /_hooks ignores allow lists, because a provider calls from its own network, but block rules still apply to it.
With sign-in
network_mode sets how network rules combine with sign-in. It is a setting on the distribution, changed with PUT /v1/distributions/{id}/access/network-mode.
network_mode | Allowed visitor | Not allowed | Blocked |
|---|---|---|---|
enforce (default) | Signs in if the site requires it | 403 | 403 |
login_fallback | Skips sign-in | Signs in | 403 |
login_fallback only changes anything on a site that requires sign-in. On a public site it acts like enforce.
The refused page and the lookup host
A refused visitor gets a 403 page in English and Japanese, with no-store and noindex, showing the address and country Edge saw. https://ip.edge.deca-dev.com/ returns the same values for whoever opens it, as JSON, or as plain text with ?format=text. Network rules see the same address.
Rule changes and network_mode are live within seconds. Neither creates a deployment, and a rollback never changes them. Creating ip_allow rules with caller_ip set fails with NETWORK_SELF_LOCKOUT when that address would be refused, unless confirm is true.
Sessions
Sign everyone out rotates the cookie key. A single sub is recorded until the session would have expired. A distribution holds 1,000 of those records (ACCESS_REVOCATION_LIMIT).
Weakening access
Turning login off, dropping require_mfa, or removing a method needs permission to change access. Without it the response is 403 ACCESS_DOWNGRADE, and the message names the fields. The same check runs when a deployment is created with config.access and when a deployment is rolled back.