Remote Access Control
Click the lock icon on a page or API block and give it a scope. Use *public for everyone, *loggedin for any signed-in user, or a scope of your own. A block with no scope at all is closed, not public. API endpoints can add a rate limit and a throttle.
Scopes decide who may open a page or API
You assign scopes to users, and blocks require them. For a tutorial on giving a user a scope, see Giving Users a Scope.
Blocks that accept scopes show a lock icon. A web_page starts without any scope, so set one before you expect visitors.
- Closed lock: the block has at least one scope, and none of them is
*public. The user needs one of those scopes. - Open lock: the block has
*public, or no scope at all.
403 ENDPOINT_NOT_PUBLIC. To publish something, select *public explicitly. Manage scopes in the modal behind the lock
Click the lock icon to open the Scopes Management Modal. In it you can:
- Select additional scopes: choose existing scopes to grant access to the block.
- Deselect scopes: remove scopes that are no longer required.
- Create a new scope: type the name into the search input. A green button appears that creates the scope.
Scopes with a built-in meaning
| Scope | Who gets in |
|---|---|
*public |
Everyone, with no login required. |
*loggedin |
Any signed-in user. |
* |
A user holding this wildcard passes every scope check. |
*ip:<entry> |
A client address matching the entry: an address, a CIDR range or a hostname. On an API endpoint, the address must match and any other scope must still pass. On a page, a matching address gets in without any other scope; give the page another scope as well, because an *ip: entry on its own does not keep others out. |
A new RUAL cluster starts with *public and *loggedin. Any other name is a scope of your own.
What a refused visitor gets
| Request | Answer |
|---|---|
| Opening a web page, not signed in | A redirect to /login?redirect=... |
| Opening a web page, signed in without the scope | 403, a page saying they have no access |
| A web action, not signed in | 401 |
| An API call without a valid token | 401 INVALID_ACCESS_TOKEN |
| An API call with a token but without the scope | 403 SCOPE_ACCESS_FORBIDDEN |
An API call from outside the *ip: range | 403 IP_ACCESS_FORBIDDEN |
| An API endpoint with no scope at all | 403 ENDPOINT_NOT_PUBLIC |
A browser that navigates to a refused API endpoint gets a readable status page instead of the JSON error. A state page shows the login page to anyone its scopes refuse.
Web actions have gates of their own
A web_action is posted to its page's URL, so the page's scopes decide first. Then the action's own gate applies:
- When the action has scopes of its own, those decide.
- When it has none, the visitor needs the scopes of every
web_pagein the blueprint. A public page is never the way in to an action written for an admin page in the same blueprint.
So when one blueprint holds a public and an admin page, give an action the public page uses the scope *public. A request from another website is refused either way. See Escaping and Security.
API endpoints add a rate limit and a throttle
On top of scopes, API endpoints have two more options, introduced in RUAL Core v13.0.7. You find both on the API block, each opening a settings modal with an enable switch.
Rate limit
Counts requests. Up to the maximum within the timeframe they pass; the rest are blocked until the timeframe resets.
Over the limit: 429 TOO_MANY_REQUESTS with a Retry-After header.
Throttle
A lock and wait: requests with the same key run one at a time. The lock is released when the request ends.
Still locked after the timeout: 429 THROTTLE_TIMEOUT.
The type sets what is counted or locked together
Both modals offer the same five types:
| Type | Applies to |
|---|---|
| URL | The entire API URL: all methods, all users. |
| URL + User | The entire API URL: all methods, per user. |
| Method + URL | The URL and the method: per method, all users. |
| Method + URL + User | The URL, the method and the user: per method and per user. |
| Custom | A key you write, in the Custom key field. {{ user_guid }} and {{ name }} for a URL parameter :name are filled in. |
The user is the signed-in user's guid. A caller who is not signed in is identified by client address.
Rate limit: maximum requests in a timeframe
- Max requests in timeframe: how many requests the key may make.
- Timeframe in seconds: the length of the window.
With a timeframe of 30 seconds and a maximum of 10, the key can make up to 10 requests within 30 seconds. Any further requests in that timeframe are blocked.
An endpoint without a rate limit of its own falls under the cluster baseline: by default 1200 requests a minute per client address for anonymous callers, and 600 a minute per session for signed-in ones. The http_default_rate_limit_* cluster settings change these, and 0 turns a tier off.
Throttle: a timeout for the wait
- Timeout: how long, in seconds, a request waits for the request ahead of it. With a timeout of 10, a second request waits up to 10 seconds for the first to finish, and then runs or is refused. Without a timeout it gets a single attempt.
Next steps
Giving Users a Scope Assign the scopes your pages and endpoints ask for. Escaping and Security Who may run which web action, and how a web page protects itself. Serving Protected Files Put a private asset behind a scope.Frequently asked
How do I make a RUAL page or API private?
Click the lock icon on the block to open the Scopes Management Modal and assign a scope. A page without scopes is closed to everyone but developers: *public opens it to everyone, *loggedin to signed-in users, and you can create a custom scope by typing its name into the modal's search input.
How do I add a rate limit to a RUAL API endpoint?
Open the endpoint's rate limit settings, enable it, pick the key type (URL, URL + User, Method + URL, or Method + URL + User), and set the maximum requests within a timeframe in seconds. Additional requests within that timeframe are blocked.
What is the difference between a rate limit and a throttle in RUAL?
A rate limit caps requests within a timeframe, while a throttle runs requests with the same key one at a time: each waits up to the timeout and then gets a 429. Both are configured per endpoint with the same key-type options, and both were introduced in RUAL core v13.0.7.