Technology handbook
Arcjet
Bot detection, rate limiting, abuse prevention, validation and security rules in application code.
- Topics
- 24
- Sections
- 4
Extension points
aj.protect
The single call that evaluates every configured rule against a request and returns a decision.
- Await aj.protect before performing the protected operation.
- Pass the request and any fields required by configured rules.
- Branch on the returned decision before continuing the handler.
defineCustomRule
Supply your own evaluate function, returning ALLOW or DENY from data the SDK cannot know.
- Define the rule's validation and decision behavior explicitly.
- Return the result shape required by the installed SDK.
- Test allowed, denied and unexpected-input cases.
withRule
Add a rule for one route on top of the client's shared configuration.
- Derive a client with additional rules for a specific route.
- Keep shared baseline rules on the original client.
- Avoid leaking one request's dynamic configuration into another.
Decision inspection
Read conclusion and reason to decide what to return, rather than trusting a boolean.
- Inspect the conclusion and reason instead of guessing from status text.
- Review individual rule results when several protections run.
- Distinguish denied requests from protection-service errors.
hasFailedOpen and errorResults
Detect a request that was allowed only because a rule could not be evaluated.
- Detect failed-open protection instead of treating it as a clean allow.
- Inspect error results to identify rules that could not complete.
- Apply the route's documented fallback policy and record the failure.
Result inspectors
Helpers such as isSpoofedBot examine the results a rule produced, after the decision.
- Use supported inspectors to narrow individual rule-result types.
- Check bot verification or other specialized results explicitly.
- Do not cast every result to the same rule shape.
DRY_RUN mode
Run a rule in logging mode first and read what it would have blocked before turning it live.
- Run new protections in DRY_RUN to observe proposed denials.
- Review false positives before changing enforcement to LIVE.
- Track dry-run findings separately from blocked traffic.
- Test unusual clients before enabling blocking behavior.
- Promote each tuned rule to enforcement deliberately.
Core model
Protect calls
Evaluate configured rules at a point in a request handler.
- Create and reuse a configured Arcjet client for the application.
- Supply route-specific request cost and identification fields.
- Place protection ahead of expensive database or model calls.
Decisions and conclusions
Read whether a request is allowed, denied or merely flagged.
- An allowed conclusion is distinct from a denial or evaluation error.
- Use the decision reason to select an appropriate HTTP response.
- Preserve the decision identifier for troubleshooting.
Rule composition
Combine several rules and understand which decision wins.
- Combine bot, rate-limit and Shield rules as needed.
- Give each rule an explicit mode and configuration.
- Inspect the combined decision and its per-rule evidence.
Characteristics
Key a rule on user, API key or another stable identifier.
- Define the attributes that identify one rate-limit subject.
- Prefer authenticated user identity when limits are per account.
- Trust proxy-derived IP information only from configured proxies.
Framework integration
Add protection in Next.js, Node, Bun or Deno handlers.
- Use the adapter matching the framework's request object.
- Keep the Arcjet secret key in server-only configuration.
- Verify behavior in the deployed runtime as well as local development.
Rules
Bot detection
Distinguish automated clients and allow the ones you want.
- Allow intended bot categories rather than trusting a user-agent string.
- Inspect available verification signals for claimed known bots.
- Separate unwanted automation from legitimate monitoring or previews.
Rate limiting algorithms
Choose fixed window, sliding window or token bucket for the traffic shape.
- Use token buckets to permit a controlled burst of requests.
- Use fixed or sliding windows for interval-based quotas.
- Match request cost and identity scope to the protected resource.
Shield
Detect common attack patterns against the application.
- Evaluate request signals before vulnerable application processing.
- Combine Shield with normal input validation and authorization.
- Review detected attacks without logging sensitive request bodies.
Email validation
Reject disposable or undeliverable addresses at signup.
- Check address syntax and supported risk signals at signup.
- Decide whether disposable or other address categories are acceptable.
- Keep email ownership confirmation as a separate step.
Sensitive information detection
Catch secrets or personal data in request payloads.
- Choose which sensitive entity types to detect in supplied text.
- Apply the configured redaction or denial action before downstream use.
- Test domain-specific false positives with representative samples.
Custom rules
Express an application-specific policy alongside the built-ins.
- Express application-specific conditions using the supported rule contract.
- Keep custom checks deterministic and bounded in execution time.
- Document what happens when the custom evaluator fails.
Operating
Choosing a key
Prefer an authenticated identity over a raw IP address.
- Use the protected resource's owner as the limit subject.
- Avoid a shared IP limit unintentionally grouping unrelated users.
- Prevent callers from freely choosing another user's identifier.
Handling denials
Return a clear status and message rather than a silent failure.
- Return 429 for rate-limit denials when appropriate.
- Use a generic refusal for other blocked requests.
- Avoid exposing rule internals that help attackers tune requests.
Local and CI behaviour
Keep rules from blocking development and test runs.
- Exercise allow, deny and error branches with controlled fixtures.
- Account for local addresses and missing production proxy headers.
- Keep CI keys and rule modes distinct from production.
Logging and tuning
Use recorded decisions to adjust thresholds before enforcing.
- Correlate rule decisions with route, account and request identifiers.
- Review denial trends and legitimate-user complaints together.
- Exclude secrets and unnecessary personal data from diagnostics.
Performance
Understand the latency a decision adds to a request.
- Reuse the client and avoid repeating protection calls unnecessarily.
- Measure added request latency under realistic traffic.
- Set a deliberate failure policy for latency-sensitive endpoints.
Layered defence
Treat application rules as one layer beside platform protections.
- Combine application protections with authentication and resource permissions.
- Keep infrastructure-level filtering and application rules complementary.
- Reassess controls when a new endpoint exposes a costly operation.
Sources
- Arcjet official documentation