Dashboard and API Integrations

Keep the two integration surfaces separate

Authentication, request schemas, and lifecycle behavior are different. Do not reuse assumptions or credentials between the two surfaces.

Pair an Agent with an Instance

1. Register or select the target Instance in the authorized Company.
2. Generate a one-time pairing code for that Instance.
3. Run the connection command on the Magento host as the operating-system user that will submit scans.
4. Confirm the Magento root is readable, Agent storage is private, and status identifies the intended Instance.

php magebean.phar agent:connect \
  --code=MB-N77V-XKNF \
  --magento-path=/var/www/magento

php magebean.phar agent:status
php magebean.phar agent:doctor

The Agent pairs with an Instance, not an Assessment. The raw Instance-scoped token is shown only once; the server stores it hashed, and it remains revocable and rotatable. Do not place pairing material in source control, Tickets, reusable shell history, or CI logs.

Submit scans for the Instance

A Scan Run belongs to the paired Instance and should use an idempotency key so retries do not create duplicate Runs. Associate each Run with the current deployment Revision and identify whether it is full or partial.

php magebean.phar agent:tick
php magebean.phar agent:cron
php magebean.phar agent:cron --install

One Scan Result may update matching automated Items in multiple relevant active Assessments for the Instance. A new production Revision makes older results visibly stale and requires a current full scan. Magebean SaaS does not remotely execute the CLI in the MVP.

When the host should no longer submit scans, run agent:disconnect. Revoke or rotate its token through the authorized Instance controls.

Protect agent credentials and state

Agent data is stored under $MAGEBEAN_HOME when set, otherwise under ~/.magebean. The credential file contains the raw Instance-scoped bearer token and is created with private permissions.

• Run the agent under a dedicated, least-privilege account where practical.
• Do not copy credentials.json into artifacts, backups with broad access, or support messages.
• Protect pending uploads and logs as assessment data.
• Disconnect before re-pairing or decommissioning a host.

Follow scan API conventions

Clients should send Accept: application/json. Requests with JSON should send Content-Type: application/json. Prefer versioned /v1/... routes over legacy paths.

Read-only routes may be public, but integrations must not assume every deployed route is anonymous. Treat 401 and 403 as authentication or authorization failures and follow the deployed access policy.

Handle HTTP status codes defensively. Do not treat undocumented response fields, pagination, error shapes, or caching behavior as contractual.

Know what data crosses the boundary

API-backed rules send endpoint-specific JSON fields rather than uploading composer.lock itself. Package advisory and status requests can contain package names and installed versions. Adobe patch requests include product, installed version, client metadata, and compatibility fields documented in the API reference.

Ordinary HTTPS connection metadata remains visible to the receiving service. Remote scans also connect to the selected storefront. Review the evidence and data-handling guidance before sharing logs or artifacts.

Integration troubleshooting

• Run agent:doctor and resolve failed prerequisites before debugging polling.
• Use agent:status to confirm endpoint, Magento path, remote state, and last polling time.
• Check credential ownership and permissions without printing the token.
• Confirm outbound HTTPS and DNS access to the intended Magebean service.
• Review verbose logs before sharing because they may contain environment-specific IP, proxy, and TLS information.
• For API requests, inspect the HTTP status and documented request schema first.

If sensitive logs or credentials may have been exposed, revoke the relevant access before continuing diagnosis.