One configured task.
An explicit result contract.

Integration quickstart

Prepare the integration before sending a request.

1. Configure a trusted caller. Obtain a bearer access token and a signed V2 execution intent from your trusted issuer. The organization, invocation identifiers, task and version must match the integration configuration.
2. Configure the execution. Enable a supported technical-task mapping, its output profile, provider credentials, provider networking and the required quota entitlement. A new account or SDK installation alone is not sufficient.
3. Use a test environment first. Supply only context permitted for the configured provider. The request below can consume provider usage; it is not the local landing-page demonstration.

1. Install the PHP helpers

composer require robo-meister/flow-beacon-api

Requires PHP 8.2+ and Composer 2. Choose a released SDK version that includes Robo\AuthSdk\ExecutionResult; confirm it against your lockfile. The SDK provides verification and parsing helpers, not an HTTP execution or polling client.

Package on Packagist ↗ · SDK source and README ↗

2. Call the execution endpoint

This example uses curl and jq. Set FLOWBEACON_BASE_URL to your configured test deployment and obtain the two tokens through your integration. Keep credentials on the server; do not place them in a public page or commit them.

# Required environment: FLOWBEACON_BASE_URL, ACCESS_TOKEN, EXECUTION_INTENT
# The intent must authorize the configured task and its output profile.
jq -n --arg intent "$EXECUTION_INTENT" '{
  prompt: "Prepare a review brief. Context: supplier agreement draft v3; review owner unknown.",
  mode: "auto",
  execution_intent: $intent,
  result_contract: "flowbeacon.execution-result.v1"
}' > request.json

curl --silent --show-error --fail-with-body \
  --request POST "${FLOWBEACON_BASE_URL%/}/call" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json

# Parse response.json only after a successful HTTP response.
# Delete request.json after use: it contains the signed intent.

Keep the same authorized invocation and request body when resolving an uncertain outcome. Do not automatically issue a new invocation after a timeout. Request validation failures may use an HTTP error response outside the execution-result envelope.

3. Read the result in PHP

After a successful HTTP response, parse the saved response. Treat malformed or unsupported output as an integration error. This example displays the outcome; it does not update a business record.

<?php
require 'vendor/autoload.php';

use Robo\AuthSdk\ExecutionResult;

try {
    $raw = file_get_contents('response.json');
    if ($raw === false) {
        throw new RuntimeException('Response is unavailable.');
    }
    $payload = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
    $result = ExecutionResult::fromArray($payload);

    if ($result->isPending()) {
        echo "Pending: preserve correlation and resolve the existing invocation.\n";
    } elseif ($result->isFailed()) {
        echo "Failed: inspect the error and apply your recovery policy.\n";
    } elseif ($result->isCompleted()) {
        echo "Completed: validate output and request business approval.\n";
        // Inspect $result->outputSchema and $result->outputData.
        // Do not apply business changes based only on technical success.
    }
} catch (Throwable $error) {
    fwrite(STDERR, "Response could not be validated. No changes applied.\n");
    exit(1);
}

Result handling

Handle each outcome explicitly.

Execution result V1 contract ↗ · Execution intent V2 contract ↗

Capabilities & availability

Implementation is only part of readiness.

This guide describes the signed, auto-mode execution path with the V1 result contract. It is not a statement that every deployment or account has these capabilities enabled.

Plans & pricing · Integration support

Responsibility boundaries

Technical success is a proposal for your application.

• The caller chooses which source context may be sent and checks business eligibility.
• Token verification establishes the validated identity and intent claims; it does not establish legal or business approval.
• FlowBeacon validates and executes the configured technical request. The negotiated result must satisfy its output contract.
• The caller checks domain rules, source freshness and permissions before accepting or applying the output.
• The SDK does not send execution requests, poll automatically or apply business outcomes.