Security
ReactiveAdmin adds an API on top of your ActiveAdmin resources. It keeps ActiveAdmin's authentication, authorization, and write path, and it adds guards of its own. This page describes what the gem enforces, what your app must still do, and how to handle sensitive data, such as PII or PHI.
Authentication
The API runs your ActiveAdmin authentication_method before every action. A request that fails authentication gets a JSON response, not a redirect:
{ "code": "unauthorized", "message": "Authentication required", "location": "/admin/login" }The location is the URL your authentication method redirects to. The client uses it to send the operator to sign in. The status is 401.
Authorization
Every endpoint checks ActiveAdmin's authorization adapter, the same one that guards the classic pages. The default adapter and ActiveAdmin::PunditAdapter both work.
- The manifest requires read permission on the namespace's root page. The
after_authorizehook runs after that check. - Index, show, and forms require the matching read, update, or create permission on the resource.
- Custom member, collection, and batch actions are authorized before the action runs.
authorize_custom_actionscontrols how strictly. The default,true, checks each action through the adapter.:match_active_adminchecks only what ActiveAdmin checks itself. - Each row and record carries a
permissionsobject, so the client can hide controls the user can't use. The server still checks every request, so the object is for display only. - Form choices (
_optionsand_options/lookupwithcontext=form) need what the form itself needs: create permission when there is noid, update permission when there is one. A page form's choices need the permission of the action the form posts to.context=filterneeds only read. Without them the answer is403, as fornewandedit. - Typeahead options are limited to the rows the user may read, when
scope_options_by_policyis on. Sources can opt out withpolicy: false. Use that only for lists that hold no restricted data.
A denied request returns 403 with code forbidden and the message "Not authorized". Authorization runs through the adapter, so custom adapters and Pundit policies apply without changes.
The after_authorize hook
Some base controllers verify authorization in their callbacks. Under Pundit, for example, a verify_authorized callback fails unless something marks the request as authorized. Set after_authorize to do that once the manifest passes:
config.after_authorize = ->(controller) { controller.skip_authorization }Exposure
Authorization decides who may read a resource. Exposure decides whether the API serves it at all. With config.expose = :listed, the API serves only the resources and pages you name, so a new or forgotten resource stays classic-only until someone lists it. Set it for any app that holds sensitive data:
ReactiveAdmin.configure do |config|
config.expose = :listed
config.exposed_resources = ["author_contracts"] # nested-only or hidden keys
endA resource or page is exposed when it:
- is placed in
ReactiveAdmin.menu(orreactive { menu path: [...] }), - has its key in
config.exposed_resources, or - declares
reactive { expose true }.
The namespace's root page is always exposed, so the shell can load. A nested-only resource, one whose belongs_to is required, also needs its parent to be exposed. reactive { expose false } denies a resource even when something lists it.
Everything else answers 404 with code not_found on every endpoint: index, show, forms, writes, actions, _meta, _options, _value, CSV and _pages. The check runs after authentication and before authorization, so a signed-out client still gets 401, and a signed-in one learns nothing about what exists. The manifest, the menu, and record references leave out unexposed resources. The classic admin is unaffected.
rake reactiveadmin:doctor reports exposure_permitted_not_exposed (what the policy permits for the doctor user but you haven't exposed) and exposure_unknown_key (a listed key that matches nothing).
API guards
Authorization says who may act. Some actions must not run through the API at all, whoever the user is, or only for some callers: granting superadmin, changing roles, impersonating another user. Declare an api guard and the server refuses them on every API request, so they stay out of reach of the React client and of anything else that dispatches through the API, such as an MCP server. The classic admin is unaffected.
ActiveAdmin.register AdminUser do
permit_params :name, :email, :role, :superadmin
api :deny, only: [:impersonate, :destroy], reason: "Impersonation happens in the classic admin"
api :deny, attributes: [:role, :superadmin], reason: "Roles are changed in the classic admin"
api :session_only, only: [:update]
member_action :impersonate, method: :post do
# ...
end
endWith this, POST /api/admin/admin_users/7/impersonate and DELETE /api/admin/admin_users/7 return 403, so does any write that includes role or superadmin, and so does an update that authenticates with a token instead of a session. The same requests to /admin/admin_users/... work as before. See DSL for the guards (:deny, :read_only, :session_only, and your own) and their options.
What the server does:
- It decides by the controller and action that will run, not by what the manifest advertises. The check runs for every API request: the mount path, a classic URL requested with the
application/vnd.reactiveadmin+jsonmedia type, a session cookie, a bearer token. It runs after authentication, so a signed-out client still gets401, and next to exposure, before authorization and before any callback or action of yours acts. A second check immediately before the action runs covers a controller that skips authentication. A guard you registered runs here, with the user and the request. - It answers
403with codeapi_denied, amessage(yourreason:, or the guard's default), theguardthat refused (deny,read_only,session_onlyor your name), andclassic_url, the classic page of the same request: the page itself for a GET, else the record's or the resource's page. A refused write that includes guarded attributes also lists their names inattributes, never their values. - It fails closed. Guards stack and any refusal wins. A registered guard that returns false, raises (the error stays out of the response and the log) or has been removed refuses. An unknown guard name stops the boot.
- It closes the side doors. Batch actions are matched by name, so
POST .../batch_actionwithbatch_action=promoteis refused.?_method=deleteand other method overrides land on the action that would run, and are refused. A format suffix other than the API's own (.json,.xml) is a404. Form choices of a refused form are refused. Forms in a page's content that post to a refused action are refused when their choices load and when they submit. A resource denied whole also drops out of the manifest, the typed cross-links, and the menu, where it stays as a link to its classic page. - It tells each caller the truth.
:session_onlyis the one guard that depends on how the request authenticated, which the server knows from the request itself. The metadata caches are kept apart by it, so a token never reads what a session was shown. - It publishes
write_rejected.reactiveadminwithcode: "api_denied"and theguard, for every verb, because a GET can act too. The event carries the resource, action, record id and user id, never params or values.
Reading is unchanged for attribute guards: a guarded attribute still shows in index, show and forms, read-only, with a link to the classic admin. Use mask to keep a value out of the API.
Things to know:
- Attributes are matched by key name at any depth of the request's params, so
author_attributes[profile_attributes][role]is caught, and so is aroleinside a JSON column. For an association, its foreign key, its ids and its_attributescount as the attribute. Only unsafe verbs count: GET requests may carry arolefilter. apiguards don't protect classic URLs. The classic admin keeps answering in any format ActiveAdmin allows, with whatever authentication the host accepts there. The gem never authenticates a bearer token on a classic route, so a token can't reach them; a host that adds its own token authentication to classic routes reopens the gap.:session_onlytrusts the host's bearer adapter to tell tokens from sessions. A custom guard that checksrequestheaders does too.- A name that matches no action guards nothing.
rake reactiveadmin:doctorlists every declaration as an accepted decision, and reports a name that matches no action asapi_guard_unknown_action. - MCP requests also answer to the resource's MCP mode, read-only by default. The mode acts as one more guard on those requests only: it narrows what the guards leave open, and a guard narrows what the mode allows. Neither widens the other.
Format lockdown
The API mount answers only in its own format, plus CSV exports on index. Requests for other formats return 404 with code not_found:
GET /api/admin/authors/:id.jsonand.xmlreturn404. They would serialize whole records.GET /api/admin/authors.csvreturns the CSV export, which honors yourcsv doblock and the current filters and scopes.
A request for an unknown path under the mount also returns 404 JSON, not the host's HTML error page.
Filters and search
The API honors only the Ransack predicates that a declared filter can produce. A q[...] key that no filter explains returns 400 with code invalid and a message that names the key:
{ "code": "invalid", "message": "Unsupported filter: npi_null" }This keeps q from probing columns the page never shows. A filter whose if: or unless: hides it from the user doesn't count, and its options answer 404. Classic pages aren't affected by this guard.
The options of a filter on a plain column are the distinct values of the rows the user may read: the resource's scoped collection under its authorization scope.
Typeahead searches cover only the source's search columns. The search matches the start of words, and pasting an id returns that record. Choose the label of an option source with care, because anyone who can read the source can see its labels.
Page size, sorting, exports and rate limits
ActiveAdmin accepts any per_page and sorts by any column. The API bounds both, and budgets the endpoints that are cheap to call and costly to serve.
per_pageis clamped, not rejected, tomax_per_page(default100). A resource's ownmax_per_pagestill applies, and the sizes it offers (per_page: [25, 250]) raise the cap for it. A value that isn't a positive integer uses the resource's default page size. A resource with pagination turned off keeps its ownmax_per_page.ordermust name a column the index shows and marks sortable (by itssort_key, soorder_byclauses work), or be the resource's defaultsort_order. Anything else returns400with codeinvalidand the messageUnsupported sort: <key>. Sorting by a hidden column would reveal how its values compare, so the allowlist applies to exports too. The message carries the key only.- Export columns. A resource without a
csvblock exports the attribute columns of itsindexblock (columns that a block computes are left out), or the implicit default columns when it has no table index. The table index decides whateverasview is requested. Understrict_defaults, such an export returns422unless a table index block supplies the columns; it also returns422when that block fails. Only the implicit defaults leave out sensitive columns: columns an index block names are exported as declared. Classic exports keep ActiveAdmin's columns. Withmask_csvon, masked keys inside json columns are masked in any export. - Exports stop at
max_export_rows(default10_000). A larger export returns422with codeinvalidand "Narrow your filters to export fewer than N rows". The check is aLIMIT n+1count before streaming. Set it tonilto remove the limit. - Rate limits give each user a budget per bucket and window, counted on
Rails.cache. Over budget returns429with coderate_limitedand aRetry-Afterheader in seconds. The buckets areoptions(typeahead search),lookup(labels for selected values, batched per form),export,value(full json values), anddefault(every other API request):
config.rate_limits = {options: [30, 10.seconds], lookup: [120, 1.minute], export: [5, 1.minute], value: [60, 1.minute], default: nil}A bucket set to nil is unlimited. config.rate_limits = false turns limiting off. Budgets key on the user id, never the IP address. They need a cache store shared by your processes. A null store, or a cache error, leaves requests unlimited.
Each export emits export.reactiveadmin with resource, user_id, filters (the q keys, never the values), scope and row_count. Subscribe to it for your audit trail, as with value_viewed.reactiveadmin:
ActiveSupport::Notifications.subscribe("export.reactiveadmin") do |*, payload|
Audit.record("export", payload)
endActions and buttons
The header lists a member or collection action only when one of these is true:
- An action item or a link in the content references it.
- You expose it with
exposein thereactiveblock.
An if: lambda that raises hides the action. A button the host meant to withhold stays hidden. See DSL.
Background requests
Clients mark metadata requests that they make without the operator asking for a page. They send the header X-Reactiveadmin-Background: 1.
The route decides what can be background, not the header. Only these GET endpoints honor it: _manifest, _session, {resource}/_meta, {resource}/_options (and its lookup), and {resource}/_labels. They carry no record data beyond display names. For everything else the header is ignored, so these are always views:
show,index,new, andedit_value- pages and actions
- CSV exports and all writes
The gem exposes the decision in two ways:
config.on_background_requestruns for background requests before your own callbacks. Use it to skip view audits, or to stop background traffic from extending an idle session.ReactiveAdmin.background_request?(request)returnstruefor those requests. Call it from your own callbacks, such as the one that records page views or refreshes the session. It isfalsefor record data whatever the header says, so acurlthat sets the header still produces an audit event and extends the session.
Lookups that return sensitive names are background for sessions and page views, but they are still audited; see Lookup audit.
The header can still be set by hand, but the only requests it can hide are metadata ones. Per-record reads cannot skip your audit, and rate_limits[:default] bounds how fast anyone can scrape them. Set a default budget in your host.
The standalone client does not prefetch records. Opening a record always sends a fresh request, even when the cache holds the record, so every open is audited. The command palette's recent records ask GET /admin/{resource}/_labels?ids= for display names only. Each record needs READ, as in show; ids that are missing or refused are omitted, and at most 20 ids are looked up. rake reactiveadmin:doctor marks its samples as internal, so hosts keep them out of the audit too.
Sessions and CSRF
The API uses the session cookie, so the client and the API must share an origin. In development, the Vite proxy handles that. In production, serve the client from the same host as the admin.
Writes need a CSRF token:
- The client calls
GET /api/admin/_session. The response includes the current user and acsrf_token. - Each write sends the token in the
X-CSRF-Tokenheader. - A missing or stale token returns
422with codeinvalid_csrf. The client fetches a new token and retries once.
Frame writes follow the same rule. The client moves the form's CSRF field into the header.
Bearer tokens
A host that sets config.auth can accept bearer tokens on the same API, for agents and scripts (see MCP). A request under the API mount ({mount_path}/{namespace}/) with an Authorization: Bearer header is authenticated by the token alone. Anywhere else, including classic routes such as /admin/... in any format, the header is ignored and the session decides:
- The session and its cookies are never consulted, and the cookies are dropped before the host sees them. A bad token is
401, even when the request also carries a valid session. - CSRF is skipped for these requests only. A browser can't attach an
Authorizationheader to a cross-site request, so there is nothing to forge. - The token's user is the current user for the authorization adapter and for host code, so a Pundit policy sees the same user it would for a session.
- A resolver that returns
scopes:limits the token: reads needmcp.read_scope, writes needmcp.write_scope. GET and HEAD are reads, except for a GET custom action listed inreactive { unsafe_gets ... }. A missing scope is403with codeinsufficient_scope.
Writes
Writes run through ActiveAdmin's own controller, as HTML. Validations, callbacks, controller do overrides, and flashes all run as they do in the classic admin. The gem then translates the result into JSON:
- A redirect becomes a
200or201response withok,id,message, andlocation. - A validation failure becomes a
422with codeinvalid, and field errors undererrors.
Every successful write and every rejected write from a signed-in user publishes an event. See Write audit.
GET actions that change data
GET and HEAD are reads, by verb. A GET action that redirects, downloads or previews stays available to read-scope tokens and api :read_only, is not write-audited, and needs no MCP confirmation. If a GET action mutates data, list it in reactive { unsafe_gets :name } to hold it to what a write is. See unsafe_gets.
Optimistic locking
Two operators can open the same record and save changes that overwrite each other. The gem guards updates with a lock token that the form response carries:
"lock": { "field": "lock_version", "value": "3" }Send the object back unchanged as the top-level lock in the update body:
{ "author": { "email": "ada@example.com" }, "lock": { "field": "lock_version", "value": "3" } }The gem picks the field. It uses lock_version when the model has Rails' optimistic locking, and updated_at otherwise. An updated_at token doesn't move when only nested rows change, so prefer lock_version for models with has_many forms. Create requests don't need a token.
- Missing token. With
config.require_lock = true(the default), an update withoutlockreturns400with codeinvalid. Reload the form and try again. - Stale token. A token that no longer matches returns
409with codestaleand the message "This record changed since you opened it." - Row lock. For
updated_at, the gem holds a row lock from the check until the write commits (host before_actions run before it), so a concurrent update can't slip between them.
Set require_lock = false only for clients that predate locking. Those clients still get 409 for a stale token.
Retryable errors
Some host errors mean "try again", such as a busy advisory lock. Declare them, and the API answers 409 with code retry and a Retry-After: 1 header instead of a 500. The code differs from stale because nothing changed under the user: clients resend the same write, and only a stale response means "review the changes":
ReactiveAdmin.configure do |config|
config.retryable_errors = ["Billing::LockBusy"]
endAccept classes or class names. Names suit constants that reload in development. The gem checks the error and its cause, so a wrapped error still counts.
Forms that can't be submitted
A form the API can't post faithfully is marked submittable: false in its FormResponse, with an unsupported_reason. A form is not submittable when:
- an html section holds raw inputs (
input,select,textarea, or a submit button), because the sanitizer would drop them, - an input has no typed control and renders as html,
- a form block, a section, or a
form partial:raises.
Clients should disable Save for these forms. A write to one returns 422 with code unsupported. The exception is a form partial, or a record that a custom new built: their writes go through unless the form holds raw inputs.
Frames and embeds
Frame responses are sanitized twice. The server removes <script> elements, on* attributes, javascript: URLs, and srcdoc. The client then runs the result through DOMPurify. The embed response sends X-Frame-Options: SAMEORIGIN, so only same-origin pages can frame it.
Typed nodes and where markup comes from
Two rules keep text a user wrote (for example Markdown a host renders unfiltered) from becoming a dangerous typed node.
Markers. When the gem puts a JSON value into a show row, it keeps the node in a table that lives for that request and writes only a random id into the markup. The walker resolves ids from that table, and drops anything else (a data-node attribute, a guessed id) with a forged_node_marker degradation. Only json, text, empty, and form nodes can use this channel.
Provenance. The walker does interpret markup: <a data-method>, a one-button <form>, and an <iframe> in rendered HTML can all turn into typed nodes. Which ones it trusts depends on who wrote them.
- While the gem renders a request,
link_to,button_to, and the form helpers (form_for,form_with,form_tag, Formtastic) stamp the anchor or form they return with a random per-request secret (data-reactiveadmin-origin). The stamp never leaves the server: sanitizers strip it, and the secret dies with the request. Output outside a render of the gem is never stamped, so classic pages are unchanged. - Only a stamped control becomes an
actionnode, and only a stamped form becomes aframe. Adata-methodlink or a one-button form that came from a string value (raw(markdown),simple_format(record.notes),html_safeon stored data) has no stamp. A link with a non-GETdata-methodbecomes plain text. Adata-confirmlink becomes an ordinary link, and its confirm text is dropped. A form becomes sanitized html with its inputs removed. Storeddata-methodlinks inside a stamped form's frame lose the attribute. - Markup you write by hand in a template (a literal
<a data-method="delete">or<form>in ERB) can't be told from stored text, so it gets no stamp either. Build controls with the helpers. - A stamped POST control to a route of this host outside the admin and the API mount becomes a
navigateaction: the client submits a real form to it in the top window with the session's CSRF token. The server allows only this origin over http(s), a plain path, and a session request; a bearer token never gets one. The client checks the target again: http(s), same origin, not under/adminor/api, no dot segments, and nojavascript:ordata:. - An
<iframe>in markup becomes aniframenode only when its path is under/admin/, has no dot segments, and routes to a registered, exposed resource or page. Any other same-site path (an upload, a blob) becomes a link. Iframes the gem adds itself, for pages that run their own JS, always use the page's own classic URL.
This is defense in depth. Hosts should still render untrusted text through a filter: use Redcarpet's filter_html: true and safe_links_only: true, or sanitize.
Client. The client checks targets again before it renders them. An iframe src must be same-origin, an /admin/ path, and is always loaded with ?embed=1; so must a page the framed content asks to navigate to. A link is an admin path on this origin, or an http(s), mailto, or tel URL the server marked external. An action's API, form, and view paths must be same-origin. Anything else renders as plain text or not at all.
Iframes carry sandbox="allow-same-origin allow-scripts allow-forms allow-modals allow-downloads allow-popups allow-popups-to-escape-sandbox". Classic pages need their own JS, session cookie, data-confirm dialogs, CSV downloads, and target=_blank links to Sidekiq and other tools, which is why popups may leave the sandbox. The sandbox omits allow-top-navigation, so a framed page can't navigate the app away. It isn't isolation, though: same-origin scripts can lift it. The /admin/ path rule is the boundary.
HTML policy
The server applies one sanitizer policy to all HTML it renders. Two rules apply, one for content and one for frames.
For html nodes in content:
- It removes
<script>and<style>, and every tag or attribute outside the allowlist. Allowed URL schemes arehttp,https,mailto, andtel. - It keeps images and documents that load from this site, as typed
imageanddocumentnodes where it can (see below). A relative URL, the request's host, and any host inhtml_trusted_hostscount as this site. Adata:URI is kept for images only. - It replaces external images, documents, and embedded pages with a link that opens in a new tab. The link is labeled
External image,External document, orExternal page. The gem records anexternal_media_blockeddegradation.
For frame nodes, which allow forms:
- It removes
<script>,<base>,<meta http-equiv>,on*attributes,srcdoc, andjavascript:,vbscript:, anddata:URLs in links and form actions. - It points form actions at other sites to
#, and removes off-site iframes, embeds, and objects. Links to other sites stay, withrel="noopener noreferrer". The gem records aframe_offsite_targetdegradation.
List the hosts your content loads from. Use only hosts you control:
ReactiveAdmin.configure do |config|
config.html_trusted_hosts = ["documents.example.com"] # or a lambda that returns an array
endThe client builds its DOMPurify configuration from rake reactiveadmin:html_policy, so the two lists stay in step. Hosts are per deployment, so the client also reads them at runtime from the manifest (site.trusted_media_hosts) and the snapshot ships with none.
Images and documents
Images and PDFs from this site or a trusted host become typed image and document nodes instead of raw HTML. An <img> becomes an image node with a lightbox. An <embed> or <object> that declares application/pdf, or an <iframe> whose path ends in .pdf, becomes a document node that the client shows in the browser's own PDF viewer. Media inside a <details> stays typed inside its disclosure node.
- A same-site PDF must also end in
.pdf, so a same-site HTML page can't render in the viewer. A trusted host may serve a declared PDF from an extensionless URL, such as a signed CDN link. - Only http(s) URLs on this site or a trusted host become nodes. Never
data:(it stays insidehtmlfor images only),javascript:, protocol-relative URLs, or URLs with credentials. The client checks eachsrcagain against the manifest's list. - The browser loads the file straight from its host. The gem never proxies it and the client never fetches it through
fetch, so sensitive documents travel from the CDN to the browser only, as they do in classic admin. - Every request carries
referrerpolicy="no-referrer", so the admin URL (which names records) doesn't reach the CDN. For defense in depth, the host can also sendReferrer-Policy: same-originwith the app shell. - Signed URLs expire. An image that fails to load shows a notice with a link instead of a broken image. Reloading the page issues fresh URLs.
Content-Security-Policy
The standalone app sets no CSP of its own. Whatever serves the app's HTML must allow the trusted hosts, or the browser refuses them even though the client accepts them. For a host cdn.example.com:
img-src 'self' data: https://cdn.example.com;
frame-src 'self' https://cdn.example.com;
object-src 'none';frame-src covers the PDF viewer. Add object-src https://cdn.example.com only if your markup uses <object> outside the typed nodes. Keep the list in step with html_trusted_hosts: a host in one and not the other shows a blocked preview. Without a CSP the browser applies no restriction, and the client's own checks still limit loads to this site and the manifest's hosts.
Degraded responses
When the gem falls back instead of failing, it says so. Index, show, form, and page responses list each fallback in degraded:
"degraded": [
{ "kind": "implicit_column_hidden", "where": "index", "reason": "encrypted column hidden by secure defaults: secret" }
]Each entry has a kind, a structural where, and a reason. The reason names an exception class or a rule, never a record value or an exception message.
- The
X-Reactiveadmin-Degradedheader carries the count on index, show, form, and page responses. - Each entry publishes a
degraded.reactiveadminnotification withresource,action,kind, andwhere. Send it to your metrics:
ActiveSupport::Notifications.subscribe("degraded.reactiveadmin") do |*, payload|
Metrics.increment("reactiveadmin.degraded", tags: payload.slice(:resource, :kind))
endMasking
Credentials and secrets never go over the API. The gem masks their values in index cells, show rows, and form fields. An attribute counts as masked when it matches one of these:
config.masked_attributes, for names that apply across the app. Use symbols or regular expressions.reactive { mask }, for one resource.config.mask_filter_parameters, which is on by default and masks attributes that match Rails'filter_parameters.
ReactiveAdmin.configure do |config|
config.masked_attributes = [:api_key, /_token\z/]
config.mask_filter_parameters = false # if filter_parameters also lists fields operators need, such as email
endActiveAdmin.register Integration do
reactive do
mask :client_secret
end
endMasking works like this:
- A present value shows as a
maskednode. An empty value stays empty, so an operator can see that no secret is set. - A form field for a masked attribute carries
masked: trueand no value. A blank submit keeps the stored value. To clear a secret, use a custom action or the classic admin. - JSON values replace masked keys with
[masked]in_valueresponses, and a value with a masked key is never sent inline. - CSV exports mask attributes by default (
config.mask_csv, on by default): each present value is written as[MASKED]. - API CSV exports prefix any cell whose text starts with
=,+,-,@, tab or CR with', so spreadsheets don't run it as a formula. Classic exports keep AA's behavior.
Masking covers attribute values only. A column or row that a block computes is your code's responsibility.
Implicit defaults
A resource without an index or show block shows default columns. With config.implicit_defaults = :secure (the default), the gem shows these columns safely:
json,jsonbandhstorecolumns follow the JSON values rule: a summary and an auditedexpand_path, with a small value inline on show.textcolumns are truncated. An index cell, and a show row longer thaninline_text_limit, carries the first 120 characters (cut on the server) withtruncated: trueand anexpand_pathto the audited_valueendpoint. Text of 120 characters or fewer is sent whole, and so is text up toinline_text_limiton show.
It leaves out these columns:
binarycolumns, which have no meaningful display,- encrypted attributes,
- attributes in
filter_attributes, and - masked attributes, which are credentials and secrets.
Each omitted column appears in degraded as implicit_column_hidden; a shown column is not degraded, and neither is an attribute you masked on purpose with mask or config.masked_attributes. Set config.implicit_defaults = :all to get ActiveAdmin's behavior instead (full text and every column).
A truncated text node looks like this:
{
"type": "text",
"text": "Draft notes ...",
"truncated": true,
"expand_path": "/api/admin/notes/42/_value?field=body&token=eyJfcmFpbHMi..."
}_value answers a text column with { "value": "<full text>" } under the same token, read permission and audit as json. It serves only plain text columns, never with a path.
Two limits apply:
- An explicit block is never filtered. Declare an
indexand ashowblock for every resource that holds sensitive data. - The default form isn't filtered. It shows the inputs ActiveAdmin's default form shows, so declare a
formblock as well.
Set config.strict_defaults = true to serve no columns or layout for a section without a block. The response records implicit_view_blocked in degraded. rake reactiveadmin:doctor lists the hidden columns for each resource.
JSON values
A json or jsonb attribute can hold large or sensitive data, so the API summarizes it. An index cell always carries a summary. A show row carries the full value only when it is within inline_json_limit and has no masked key:
{
"type": "json",
"summary": { "kind": "object", "keys": ["bio", "links"], "size": 5120 },
"expand_path": "/api/admin/authors/42/_value?field=profile_data&token=eyJfcmFpbHMi..."
}The summary lists the kind (object or array), up to 20 top-level key names, and the size in bytes. It never includes the values.
An edit form's json control follows the same rule: a stored value over the limit, or with a masked key at any depth, comes as value: null plus summary and expand_path. The editor loads it through expand_path on an explicit click, which is an audited view. On save:
- A summarized field that is omitted,
nullor""keeps the stored value. Send{}or[]to empty it. [masked]placeholders in a submitted value take back the stored value of the same key (matched by path), and a placeholder with nothing stored is dropped. The literal is never written.
To fetch the full value, call expand_path as given. Add path to read one nested key, such as path=allergies.0:
- The
tokeninexpand_pathis a signed, short-lived proof (value_token_ttl, 15 minutes by default) that index, show or the edit form rendered this field of this record for this user._valuechecks the proof instead of rendering those pages again. A missing, forged, expired or other-user (or other record or field) token answers403 forbidden. Reload the page for a fresh link. - It authorizes
readon the record, as show does. For a token from the edit form it also requires theupdatepermission, and it requires the page that issued the token to still be served. Both are checked on every request. - It answers
404for an attribute that is neither json nor a plain text column, and for masked attributes. - It replaces masked keys with
[masked]. - It sends
Cache-Control: no-store. - It publishes
value_viewed.reactiveadminwithresource,id,field, anduser_id. Because it is a real view,on_background_requestnever applies to it.
Set config.value_token = false to go back to the unsigned _value: it then renders index, show and the edit form again on each call to learn what the field may expose, and answers 404 for an attribute none of them show.
Send the event to your audit trail without the value:
ActiveSupport::Notifications.subscribe("value_viewed.reactiveadmin") do |*, payload|
AuditLog.record(:sensitive_view, **payload.slice(:resource, :id, :field, :user_id))
endWrite audit
The gem publishes two events for writes from a signed-in user:
write.reactiveadminafter a write succeeds and its transaction commits.write_rejected.reactiveadminwhen the API rejects a write, with thecodeof the error.
Both carry resource, action, id, and user_id. A rejection also carries the code, including api_denied, with the guard, for what an api guard refused (see API guards). The id is included only when it is a plain identifier. A batch action also carries record_ids, the selected ids that are plain identifiers. The events never carry params or values.
To tell an agent's writes apart, or to join them to the tool call that made them, use the audit envelope.
Lookup audit
A typeahead search, an option lookup, or _labels can return an author's name, and none of them is a page view. When the records returned belong to a sensitive resource, each request publishes one lookup.reactiveadmin event after it is answered:
| Key | Value |
|---|---|
resource | The resource whose endpoint was called. |
field | The input searched or resolved. nil for _labels. |
kind | :search (term or listing), :lookup (selected values resolved, by _options or _options/lookup), or :labels. |
target | The sensitive resource whose records were returned. |
result_count | How many options or labels were returned. |
user_id | The signed-in user. |
The event never carries the search term or a returned name. It is one event per request, and one per sensitive field for the batched _options/lookup, never one per result. The rate limits on _options and _options/lookup bound the volume. A failing subscriber is logged and never turns the lookup into a 500.
Mark a resource as sensitive with config.sensitive_resources = %w[authors] (route keys), or in its own file with reactive { sensitive true }. sensitive false opts a resource out of the list. Choose resources whose display name is a person's name or otherwise identifies an author. A resource that only points at an author (a todo, a fee) isn't sensitive itself; its author typeahead is audited through the authors target. Staff names usually aren't sensitive.
Subscribe in the host:
ActiveSupport::Notifications.subscribe("lookup.reactiveadmin") do |*, payload|
Analytics.track(user_id: payload[:user_id], event: "Admin Lookup", properties: payload.slice(:resource, :field, :kind, :target, :result_count))
endAudit envelope
Each event above is also published as one audit.reactiveadmin event with a single shape, so one subscriber can feed your audit trail. The per-kind events don't change. The envelope adds what they lack: the request, the channel, the MCP client, a correlation id, the ids of a batch, record views, and UI switches.
Subscribe with ReactiveAdmin.on_audit. It yields a frozen ReactiveAdmin::Audit::Event and returns the subscriber, for ActiveSupport::Notifications.unsubscribe. Plain subscribers to audit.reactiveadmin get the same fields as a frozen hash.
| Field | Value |
|---|---|
kind | write, write_rejected, export, value_viewed, lookup, mcp_call, degraded, view, or ui_switch. |
user_id | The signed-in user. nil for degraded. |
resource | The route key, or nil. |
action | The controller action (create, batch_action, show), the MCP tool's verb or run_action's action, or nil. |
record_ids | Ids as strings. Every selected id for a batch action. Empty when no record applies. |
channel | session, token (a bearer token on the API), or mcp (the MCP endpoint and the requests its tools make). nil outside a request. |
client_id | The client_id your bearer block returned, or nil. |
request_id | The request's X-Request-Id. |
correlation_id | The same as request_id, except on the requests an MCP tool makes, where it is the id of the tool call's request. A write with channel: "mcp" shares it with its mcp_call, and so does a degraded raised while a tool's request renders. |
outcome | ok, rejected (write_rejected), error (a failed mcp_call), or degraded. |
at | When the event was published. |
details | What the kind adds, ids and names only: code and guard for a rejection, field for a value view, filters, scope and row_count for an export, field, type, target and result_count for a lookup, tool, http_status and duration_ms for an MCP call, type and where for a degradation, from and to for a UI switch. |
The envelope never carries params, values, search terms, display names or emails. A subscriber that raises is logged and never fails the request.
Two kinds exist only in the envelope:
view, withconfig.audit_views = true(defaultfalse): one event per APIshoworeditread that succeeds, including one whose override renders JSON itself, from the client, a token, or an MCP tool. Classic pages aren't covered; audit them in your own controllers.ui_switch: a user moved between the classic and the new admin. The switch is the browser writing thereactiveadmin_uicookie, so the server notices it on the next signed-in request and keeps a signed,HttpOnlyreactiveadmin_ui_seencookie to remember the UI it last saw for that user. A browser that never chose gets no cookie. Right after you upgrade, a user already on the new admin is recorded once as switching from classic. Concurrent requests that carry the old marker, such as two tabs reloading together, can each record the same switch; dedupe onuser_id,fromandtowithin a few seconds if that matters.
To write every event to a table:
# create_table :admin_audit_events do |t|
# t.string :kind, null: false
# t.bigint :user_id
# t.string :resource, :action, :channel, :client_id, :request_id, :correlation_id, :outcome
# t.json :record_ids, :details
# t.datetime :at, null: false
# end
ReactiveAdmin.on_audit do |event|
next if event.kind == "degraded" # metrics, not an audit
AdminAuditEvent.create!(event.to_h)
endThe subscriber runs in the request, after the write's transaction commits. Enqueue a job instead if inserting is slow.
Error codes
| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | Not signed in. location holds the sign-in URL. |
forbidden | 403 | The policy denies the request. |
not_found | 404 | No such record, or the resource isn't exposed. |
invalid | 400 or 422 | Bad input or failed validation. A 400 also covers a missing lock. |
invalid_csrf | 422 | Missing or stale CSRF token. |
unsupported | 422 or 501 | A write to a form that can't be submitted returns 422. A GET view that no mode can render returns 501. |
stale | 409 | The record changed since the form loaded. |
api_denied | 403 | An api guard refused the action, resource, page or attribute. Carries guard, classic_url, and attributes for a write. Never retry it. |
retry | 409 | A host error declared in retryable_errors. Carries Retry-After: 1. Resend the same write. |
rate_limited | Planned | The contract defines the code, but no code returns it yet. |
error | Usually 500 | An unexpected error. The message names the exception class and the resource, never the exception message. |
Logging and errors
The gem keeps record data out of its own logs and responses:
- Warnings name the resource, the section, and the exception class. They include the first backtrace frame, not the exception message.
- Unexpected errors return an error status,
500by default, with the exception class and the resource. The gem logs the class and the first backtrace frame. - Error reports go to
config.error_reporteras aScrubbedError. It carries the original class, the backtrace, and the resource, action, and request ID. It never carries the original message. The default reporter callsRails.error.report. - Doctor output names resources, sources, and counts. It never prints record data or exception messages.
- Server-Timing headers carry only the database and application durations.
Two things remain your responsibility:
- Request logs record the query string, so
q[...]values and thetermparameter appear in them. Add any parameter that can carry sensitive data tofilter_parameter_logging, in your app's initializer. Include the predicate keys, such asname_cont, if they can hold sensitive data. - Errors raised inside your own code can carry sensitive data in their messages. The gem drops the message from its own reports, but it doesn't control what your code puts in an exception before the gem sees it.
The gem sends no analytics and no client-side error reports.
The UI switch
config.ui (Roll out the new admin) lets a page load at a classic URL answer with the client's shell. What it exposes:
- No new data path. The shell is a static page, the same for everyone, and the middleware that serves it knows nothing of users, resources or authorization. Every record still comes through the API, with its authorization, exposure,
apiguards and audit. - A preference, not a credential. The
reactiveadmin_uicookie holdsneworclassic, readable by scripts, withSameSite=Lax. Setting it by hand only chooses which UI renders.ui.availablegates the interface; a user who isn't available is sent back to classic by the client, and the API doesn't depend on it. - Failure means classic.
ui.availabledefaults to nobody, and a callable that raises counts as unavailable. Without a client build, the middleware does nothing. - Switches are audited. A switch publishes an
audit.reactiveadminevent of kindui_switch; see Audit envelope. - Public assets, uncached shell. The built files are public and hold no secrets. The shell is
Cache-Control: no-storeand carries your app's default response headers and CSP nonce.
Planned
These aren't in the gem yet:
- Rate limits on the API. The contract already defines the
rate_limitedcode.
Checklist
Before you expose a resource that holds sensitive data:
- [ ]
config.expose = :listed, and the resource is placed in the menu, listed inexposed_resources, or markedexpose trueon purpose. - [ ] The
index,show, andformblocks declare only the fields the API needs. - [ ]
masked_attributesorreactive { mask }covers every credential and secret. - [ ]
implicit_defaultsis:secure, andstrict_defaultsis on if a section must never show defaults. - [ ]
require_lockistrueunless a client predates locking. - [ ]
html_trusted_hostslists only hosts you control. - [ ] Option sources declare
search:columns and a safelabel. - [ ] Actions and attributes that grant privileges or act as another user are behind an
apiguard (:deny, or:session_onlywhere the React client may use them), and your own code doesn't authenticate bearer tokens on classic routes (the gem doesn't). - [ ] If MCP is on,
config.mcp.defaultis:read_onlyor:none, only resources agents must change aremcp :full(or list the actions they need), resources with PHI that agents don't need aremcp :none, and the doctor's "MCP surface" shows nomcp_full_sensitivewarning you haven't accepted. - [ ] Custom actions have an authorization rule, and
authorize_custom_actionsistrue. - [ ] Your error reporter and log filters cover the sensitive data that can reach them.
- [ ]
filter_parameter_loggingcovers the sensitive parameters that can reach the API. - [ ] Your audit trail subscribes with
ReactiveAdmin.on_audit, or tovalue_viewed.reactiveadminandwrite.reactiveadmin, and towrite_rejected.reactiveadminif you audit rejections. - [ ]
audit_viewsistrueif you must record who opened which record through the API. - [ ] If you allow MCP, your audit keeps
channel,client_idandcorrelation_id, so an agent's writes can be traced to its tool calls. - [ ]
sensitive_resourcesnames every resource whose display name identifies an author, and your audit subscribes tolookup.reactiveadmin. - [ ] Background requests are handled in
on_background_request, if your audit needs it.