Automate links with personal API tokens

Start from Account and grant only the access the automation needs.

Open Account, find Personal API tokens and give the credential a name that identifies the system and environment, such as GitHub Actions · production. Choose read-only access for reporting or read-and-update access for link automation.

Confirm your identity before creation. OrbitPage displays the complete token once and stores only a cryptographic hash. Put the value directly into the secret manager used by the script or CI provider.

• Use a separate token for each automation and environment.
• Prefer a finite expiry and rotate before it is reached.
• Never commit a token to a repository, build log or client-side bundle.

GET the collection before changing it.

Send the token as Authorization: Bearer to GET /api/v1/links. The response contains the current links, workspace identity and revision. The same revision is returned in the X-OrbitPage-Revision and ETag headers.

Personal tokens are intentionally rejected by dashboard-only API routes. Firebase session tokens are likewise not accepted by the personal automation API.

Every write uses the revision you just read.

Use PUT /api/v1/links to replace the full collection, or PATCH /api/v1/links/{linkId} to update selected fields on one existing link. Include If-Match with the current numeric revision or weak ETag returned by GET.

A stale revision returns 409 instead of overwriting newer dashboard work. A missing revision returns 428. Successful writes validate the page schema, plan limits, workspace permissions and moderation state before publishing the new revision.

• GET /api/v1/links requires links:read.
• PUT /api/v1/links requires links:write and a links array.
• PATCH /api/v1/links/{linkId} requires links:write and preserves IDs, counters, types and system-managed fields.

Remove access at the end of the automation lifecycle.

The Account list shows the token prefix, scope, expiry and most recent use. Revoke a token immediately when a secret may have leaked, a workflow is retired or a collaborator no longer operates the integration.

OrbitPage checks the user's current workspace role on every API call. Revocation, expiry, workspace removal or loss of link permissions stops the token without affecting dashboard sessions or other personal tokens.