Integrating an external service

This guide is for operators connecting an external service to a canonical Project. The Organization owns the Project, and the Project owns its Environment-scoped runtime resources. Use the guide when you need to choose those coordinates, author the resources, and issue bounded credentials for the service. Every request remains within the authenticated Organization, Project, and Environment grants; this guide does not widen that authority.

Create the canonical resource boundary

Create or select the Organization that owns the integration, then create one Project for the consumer. The Project owns its Agents and immutable Agent Revisions. Project creation atomically creates the built-in Development, Preview, and Production Environments. Select the existing built-in Environment for the integration; do not create another one. Each starts as a logical provisioning Environment with an initial configuration head. Before creating configuration revisions or submitting a Deployment, transition the selected Environment through:

PATCH /api/v1/projects/{projectId}/environments/{environmentId}
{
  "lifecycle": "active",
  "expectedLifecycle": "provisioning"
}

This logical lifecycle transition is separate from the later generation-guarded Activation of a ready Deployment. Runtime Binding remains lazy, and an empty provider-settings collection uses the platform default; do not add credentials or infer a runtime resource solely to make the logical Environment active.

Author the consumer's Project Agents and Definition source, then publish the exact immutable Agent and Definition Revisions. Create a Release that pins the revision graph and delegate attachments. Submit a Deployment for the intended Environment and its complete Configuration Revision, wait until the Deployment is ready, and activate that exact Deployment with the Environment's current generation. Runs begin only from the active Deployment. A new revision or configuration change creates a new Release, Configuration Revision, Deployment, or Activation; it does not rewrite a prior record.

System Agents are different: they are platform-owned publications and do not receive a fabricated Project, Environment, Release, or customer configuration. Use the platform-owned publication path for those resources rather than placing them in a consumer Project.

Give the consumer a bounded API key

Create the key through the public API-key resource (POST /api/v1/api-keys) or Studio. Scope it to the exact Project, Environment, Agent, and operations the consumer needs, and choose an appropriate expiry. Key creation returns the secret only at creation; store it in the consumer's secret store and never put it in a repository, issue, log, or public configuration response.

Creation requires api-keys:create; the calling key's grants do not limit the new key's grants. Resource targets must belong to the authenticated Organization. When a key is used, its own grants and the user's current resource permissions apply. Rotate by creating a replacement with the intended scope and expiry, moving the consumer, then revoking the old key.

For GitHub-backed consumers, keep non-sensitive coordinates and feature settings in GitHub Actions Variables. Put API-key secrets, webhook signing secrets, and other credential material in GitHub Actions Secrets. Neither category changes the Perstack authorization boundary; the key's Perstack scope and expiry still control requests.

Provider configuration

Connections and provider settings are Environment configuration. Select exact same-organization credential or connection versions in an immutable Configuration Revision when the consumer needs BYOK or an external service. Do not copy a credential into Agent content or an integration repository.

An Environment with no provider setting uses the platform default. The consumer does not need a dummy provider setting, provider locator, or secret to make the default available.

Receive events safely

Create a webhook under the explicit Project Environment through the public Environment webhook resource. The create response includes the signing secret once; store it as a GitHub Actions Secret or equivalent secret-store value. The same one-time rule applies when rotating a webhook secret. Verify the signature before processing a delivery and treat delivery as at-least-once.

Use the delivery retry operation only for a dead delivery. A replay is a separate durable request for a retained original event and preserves the original event identity and attempt history. Keep the operation's Idempotency-Key when retrying the same request; do not turn an active or completed delivery into a retry.

Environment values

Environment variables and secrets are versioned configuration values. A plaintext variable may be written through the public variable resource and is returned only as safe metadata; secret values are write-only. Bind the exact variable version required by the Configuration Revision or use an explicit local non-secret value. A disabled or revoked reference fails closed rather than silently following a newer version.

After changing a variable, connection, provider setting, or Agent binding, create a new complete Configuration Revision and promote it through Release, queued Deployment, readiness, and generation-guarded Activation. Do not edit a running snapshot in place.