Self-signup with a machine identity

An agent that already runs under a verifiable identity its environment issued — a GitHub Actions OIDC token today — can sign itself up. It presents that token to /v1/identity/federate; PerSQL verifies it against the issuer’s public keys and provisions the agent its own workspace: a namespace, a main database, and a scoped token. No human in the loop, no email to verify, no app to install.

This is the keyless on-ramp for autonomous agents. (If you instead want a workflow to share a database bound to a workspace you already own, install the GitHub App — that path binds a repo to your workspace; this one gives the identity its own.)

From a GitHub Actions workflow

The job needs exactly one permission: id-token: write.

permissions:
  id-token: write

jobs:
  agent:
    runs-on: ubuntu-latest
    steps:
      - name: Sign up for a PerSQL workspace
        run: |
          # Mint a GitHub OIDC token bound to this run, audience "persql"
          OIDC=$(curl -sf -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=persql" | jq -r .value)

          # Federate it -> the agent's own workspace + a token
          curl -sf -X POST https://api.persql.com/v1/identity/federate \
            -H "Authorization: Bearer $OIDC"
          # -> { "data": { "token": "psql_live_…", "url": ".../v1/db/<ns>/main",
          #               "namespace": "…", "database": "main",
          #               "identity": "owner/repo", "created": true,
          #               "expiresAt": "…" } }

The call is idempotent per identity: the first federate provisions the workspace; every later one resolves to the same workspace and mints a fresh token. So a workflow can call it on every run without accumulating workspaces.

Using the workspace

The returned token is a standard namespace-scoped token — use it against the /v1 API like any other:

curl -sf -X POST "$URL/query" \
  -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"sql":"CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)"}'

How it works

• The agent presents a signed OIDC token. PerSQL verifies the signature against the issuer’s published keys and pins the issuer, audience (persql), and expiry — a token minted for another service can’t be replayed.
• The identity (for GitHub Actions, the repository) becomes the key for a self-owned workspace, recorded once so re-federating is a single lookup.
• The minted token is scoped to that workspace and expires on its own; re-federate to get a fresh one.

Notes

• Audience must be persql. Request the OIDC token with &audience=persql; a token minted for a different audience is rejected.
• Billing is usage-only against the workspace’s prepaid balance. A self-signed-up machine workspace starts empty — top up before its first request.
• Scope a blast radius by federating distinct identities — each gets its own isolated workspace and balance.
• More issuers (GitLab CI, cloud workload identity) are on the roadmap; the verifier is issuer-agnostic by design.