Connect an agent to a project.

1. Issue a credential

A workspace owner or admin can open Agent access, choose a project, name the connection and select permissions. Credentials expire within 90 days. Copy the secret once into your server or agent secret manager.

Never embed credentials in browser JavaScript, public source, URLs or model prompts. Your agent runtime should inject the Authorization header. Spokegrid stores a hash; the secret cannot be recovered.

2. Discover supported operations

GET /api/v1/automation/capabilities is public and lists operations, scopes, request limits and recovery guidance. This release supports reading one bound project, updating its metadata and linking existing owned sites or forms.

Deployment, CMS installation, form creation, form response access and purchases are unavailable to agent credentials. Linking a resource records an association; it does not install an integration or share service permissions.

3. Call from a trusted runtime

curl https://api.spokegrid.com/api/v1/automation/project \
  --header "Authorization: Bearer $SPOKEGRID_AGENT_TOKEN"

Omit account cookies. Read responses use the existing ProjectDetail shape. PATCH /api/v1/automation/project requires projects:write and the fields name, description, website_origin, expected_revision. POST /api/v1/automation/project/resources requires projects:links and kind (site/form), resource_id, expected_revision.

4. Recover deliberately

401

Credential invalid, expired or revoked. Ask its owner to issue a replacement.

403

Scope or current issuer role does not permit this operation. Do not keep retrying.

409

Read current state and merge your intended change. Supply the current revision. Never overwrite another edit automatically.

429

Wait for Retry-After. The per-token limit is 60 calls/minute; account limits still apply.

503

Retry reads with backoff. After an interrupted mutation, read state before deciding whether it must be retried.

Creating a credential is not replayable: if creation times out, list credentials, revoke the uncertain one and create a replacement. Ten active credentials are allowed per project.

5. Review and revoke

Agent access shows recent metadata-only activity and lets owners/admins revoke credentials. Current membership, scopes, expiry and revocation are checked on every call. An operation already executing may finish before revocation takes effect.

Audit records exclude request bodies and secrets. The API returns the latest 100 events. Project events retain the account that delegated the operation; agent audit identifies its credential separately.