Base path and access
The versioned change-engine routes live under /api/v1 on the AppsCert application origin. Use the origin configured for your environment; this guide does not assume a separate api.appscert.com host.
Human requests use the signed-in AppsCert session and organization access checks. Workload requests use an opaque bearer token bound to an organization and workload; the route checks its required scope. A bearer header alone does not grant access.
POST /api/v1/auth/exchange is specifically for a GitHub Actions OIDC assertion that matches a configured workload identity; it is not human SSO or a general API-key exchange. The returned opaque token is short-lived and carries the configured workload scopes. The same route accepts ?op=introspect with a token in the JSON body to check its active state.
Request workload access
GitHub Actions OIDC onboarding is currently managed. There is no public self-service registration route: POST /api/v1/auth/exchange only exchanges an assertion after an authorized AppsCert workload identity has been configured. An unregistered repository cannot provision itself by calling the exchange endpoint.
To request a review, use the link below; it opens your configured email client but does not send automatically, confirm receipt, or provision an identity. Email AppsCert support with the following configuration metadata:
- The AppsCert organization/tenant to which the workload should be bound.
- The canonical GitHub repository (
owner/name) plus its numericrepository_idandrepository_owner_idclaims. - The exact permitted Git ref, exact workflow reference (the full path ending in
@refs/...), and environment name, or “none” if the job does not use a GitHub environment. Current bindings compare these values exactly; do not request a wildcard or all-branches binding. - The OIDC audience you intend to request. The value must exactly match the registered binding; if you do not know it, ask support to provide the value before configuring the workflow.
- The API operations the workflow needs. Request only their minimum v1 scopes; support will confirm the exact supported scope set and whether this environment can be provisioned.
For the standalone integration example, the exact values are ref refs/heads/main, workflow reference OWNER/REPOSITORY/.github/workflows/appscert-plan.yml@refs/heads/main, and environment appscert-release-read. If the trusted-repository fallback omits the GitHub Environment, request environment none instead. A reusable workflow can supply job_workflow_ref; support must match the actual claim, not a wildcard. This AppsCert binding protects the OIDC exchange only. The GitHub read token used to download private release assets is needed before that exchange and must be protected by GitHub's own secret access controls. Review the private-release workflow prerequisites before storing that credential.
This request does not itself create or approve a binding. Wait for support to confirm that the organization and exact repository/workflow binding are active and to provide the expected audience before attempting exchange. Never email a GitHub OIDC JWT, workload token, API key, password, private key, certificate or other credential.
Once the binding is confirmed, the GitHub job that requests an OIDC token needs the job-level id-token: write permission. GitHub documents that this permission allows token retrieval; it does not grant write access to other resources. The exchange still checks the configured audience and exact identity claims. See the GitHub Actions OIDC permissions reference.
Do not confuse this flow with a dashboard API key. For Fastlane's legacy CI API, create a key with ci:read and, only if it downloads files, ci:download. See the private integration installation guide.
Read organization resources
GET /api/v1/resources requires the organization_id query parameter. A workload token needs the change:resource:read scope and a matching organization. The response is an object with a resources array.
Replace these placeholders with values from your configured AppsCert environment:
curl --fail --silent --show-error \
--header "Authorization: Bearer $WORKLOAD_TOKEN" \
"$APPSCERT_ORIGIN/api/v1/resources?organization_id=$ORGANIZATION_ID"The query is read-only at this route. Missing organization context is rejected; an invalid or cross-organization workload token is not a way to enumerate resources.
Route map checked against handlers
| Method and path | Purpose | Important boundary |
|---|---|---|
GET /api/v1/resources | List organization resources | Requires organization context and read access. |
POST /api/v1/resources | Register or update resource metadata and consumer bindings | Requires organization write access; metadata is restricted to non-secret fields. |
POST /api/v1/plans | Create or replay a change plan | Requires an idempotency key (header or body); planning does not execute a provider operation. |
POST /api/v1/operations | Register or replay a queued job for a plan | Requires an approved flag, matching plan intent, idempotency key and operation scopes. A queued response is not provider success. |
GET /api/v1/operations/{id} | Read operation, plan, steps and visible evidence | Requires organization read access and resource binding for workload callers. |
POST /api/v1/operations/{id} | Approve, revoke approval or cancel a queued operation | Requires organization write access and plan/resource scope; cancellation is not available after execution starts. |
POST /api/v1/receipts | Record a consumer's observed version as evidence | Requires a registered consumer and idempotency key; stale or mismatched receipts may be recorded as historical, not accepted. |
POST /api/v1/auth/exchange | Exchange a GitHub Actions OIDC assertion for an opaque workload token | Requires a matching configured workload identity; this is not human SSO or a public API-key flow. |
POST /api/v1/auth/exchange?op=introspect | Check an opaque workload token | Provide the token in the JSON body; never put bearer tokens in URLs. |
These routes are the versioned change-engine surface described by this guide, not every application API. Operation submission registers a job for the worker; this response alone does not assert that a provider-side effect completed. Session routes and legacy endpoints are separate from this versioned API.
Safe use
- Never paste real tokens, private keys or passwords into a guide, URL or support request.
- Use the minimum scopes for the operation and the intended organization.
- Treat resource registration and plan creation as writes; use the operation endpoint only through an authorized workflow.
- Review the handler contract and tests for the deployed release before using a request copied from another version.
For the user-facing review flow, see the certificate review guide.