Authentication and endpoint requirements

Separate service authentication from customer ownership#

For custom HTTP, save a bearer token in the Action’s credential field and validate it on your server. Use a credential dedicated to the narrow task, rather than an unrestricted administrator token. Reesponder stores the saved secret encrypted on the server and does not expose it as a widget field or a portable template value.

The bearer token authenticates Reesponder to your service; it does not establish which customer owns an order. Require widget email verification for private data, then compare verified_email on GET or customer.verifiedEmail on POST with the record’s actual owner. A trusted server-side website context integration is a separate feature and does not automatically replace this Action email check.

Do not confuse the installation token with this credential. The installation token binds a browser widget to a website. The saved provider credential authenticates a server request to your business endpoint, and it belongs outside browser source.

Public HTTPS only#

The configured endpoint must use HTTPS on port 443. URLs with embedded credentials, fragments or query strings are rejected. Localhost, .local hosts, private addresses and link-local targets are not allowed. Do not configure a database port, an internal administration console or an endpoint that requires a redirect before reaching its handler.

Reesponder resolves the hostname, checks all returned addresses and pins an accepted address to the connection. DNS resolution has a 3-second limit. This prevents a hostname from switching to a private target during the request. If your API is available only inside a private network, provide a dedicated public authenticated adapter rather than expecting Reesponder to reach it directly.

A hostname with both a public and a private DNS answer is not a safe target merely because one address works. All resolved addresses are checked. Review the endpoint's actual DNS configuration if a hostname is rejected.

Design for the request limits#

Return a small, uncompressed JSON response promptly. There is no redirect following or automatic decompression. A large provider record or long-running process should be summarized behind your adapter. For background work, record a durable request and return its reference; do not claim the downstream task is complete before it is.

Leave enough time for your handler to validate and persist a request before returning its small result. Calling several slow services synchronously can exhaust the request window even when each service works independently.

Enforce rules before changing state#

A confirmed write means the customer approved the displayed inputs. It does not override your refund policy, permissions, stock checks or eligibility rules. Validate these conditions on every request. Make ownership checks and the mutation part of a consistent transaction when your storage supports it.

The same run reference appears in Idempotency-Key and the POST body. Deduplicate it before executing the side effect. A local one-time execution claim cannot guarantee a distributed transaction across Reesponder and your destination. See idempotency and uncertain outcomes for recovery.

Recheck eligibility at execution time. A prior read saying an item was available is not a reservation, and a confirmed card does not keep stock or order status unchanged while the visitor considers it.

Handle credentials and logs deliberately#

Keep saved credentials out of website source, screenshots, conversation content and template files. When you change an endpoint or provider, enter the appropriate replacement credential and test again. When an external credential expires or is revoked, update it through the Action form; do not weaken authentication to make the test pass.

Use the run reference in endpoint logs so you can investigate a failure without dumping authorization headers or complete customer records. Return only the intended customer fields. If a read test fails, first check HTTPS reachability, authorization, JSON format and field mappings before enabling anything.

Separate service credential rotation from widget token replacement. Updating the former repairs destination authentication; replacing the latter changes every manual storefront installation. Use the control that addresses the observed failure.

Worked example: a public adapter for a private service#

Your order system runs inside a private network. Reesponder cannot connect directly to its internal host or database port. Provide a narrow public HTTPS adapter on port 443, authenticate its requests with a dedicated service credential and let that adapter make the permitted internal lookup under your controls.

The adapter accepts only the configured order reference and verified identity. It checks the record owner before returning a status summary. It does not accept an arbitrary internal URL, SQL statement or provider request object. Public reachability and application authorization solve different parts of this design.

Test the final adapter URL without depending on a redirect. Verify DNS answers are public, the TLS certificate is valid and the handler returns uncompressed JSON. Use a known order fixture for both a correct-owner and a wrong-owner request. Inspect logs to ensure Authorization and full private provider responses are redacted.

If you later add a change operation, configure it as a distinct confirmed write and implement provider-side idempotency. Do not give the read endpoint side effects simply because it is already connected.

Review each boundary independently#

Test the destination URL and DNS rules, missing or incorrect bearer credentials, a different owner's record and the response format. These checks establish reachability, service authentication, customer authorization and safe output separately. A successful network request proves none of the other boundaries by itself.

Test oversized and delayed responses with disposable fixtures. For an external write, verify recovery from a lost reply before rollout. Keep safe run references available to your incident owner without publishing credentials, code emails or full customer records in a support thread.

Distinguish a network guard from a business rejection#

An unsafe endpoint is a configuration problem at the destination boundary. Check scheme, port, embedded credentials, query string, fragment and DNS addresses. Reesponder does not follow a redirect to a different handler; use the final approved URL directly. Do not make an internal service public without adding the appropriate authentication and narrow contract.

An unavailable provider can reflect DNS, TLS, connection or timing failures. Check whether your handler received the run reference before deciding what happened. For reads, the customer may need an honest temporary-unavailable outcome. For writes, absence of a reply does not prove absence of a mutation.

A rejected provider response means the destination returned a non-2xx status. Inspect your protected provider logs for its reason. A credential problem, policy rejection and unavailable record can all produce different downstream behavior; Reesponder's safe error is not a dump of the private response body.

An invalid or oversized response occurs after connectivity but before a useful result can be accepted. Return valid uncompressed JSON within the body limit and ensure at least one mapped scalar exists. Repair the adapter rather than broadening the output allowlist to expose a large object.

Make security review a repeatable release step#

Keep a short reviewed specification for each task: permitted website, fixed destination, service credential owner, verified identity use, required inputs and allowed results. Review that specification whenever the Action or adapter changes. This is more useful than a screenshot showing a single successful test.

Use a least-privilege credential that can perform the intended operation and no broader administration. If a provider requires a different authentication scheme, translate it server-side in your adapter instead of placing credentials in URL parameters or visitor fields. The portable template should remain safe to share without secrets.

For writes, document transaction and replay handling, the meaning of the returned status and the person responsible for uncertain outcomes. Check that normal rejection conditions do not disclose another customer's data and that result links enforce their own authorization.

Finally, review diagnostics and retention. A log entry containing a run reference and error category can support investigation without retaining an entire private payload. Conversation-linked Action inputs and contact expire with conversation retention; use your own controlled business records where the process needs a longer-lived audit trail.