PlanetScale

PlanetScale connects via OAuth: click Connect with PlanetScale, authorize read access on PlanetScale, and you're redirected back with syncing already started. If your PlanetScale account can access more than one organization, pick the one to connect when prompted. Tokens are encrypted before they are stored, and the agent never sees them.

Service token alternative

If you prefer a long-lived credential, connect with a service token instead:

1. Open PlanetScale, go to your organization's Settings → Service tokens.
2. Click Create service token and copy both the token ID and the token.
3. Grant the token read access to the organization and its databases (e.g. read_databases, read_branches).
4. Paste the token ID and token into Polylane. If the token can reach more than one organization, also provide the organization name to connect.
5. Polylane validates the token and starts syncing.

Each connection covers a single PlanetScale organization. Polylane discovers its databases and their branches, including state, plan, region, and schema activity.

Troubleshooting

"Invalid service token" error

• Both the token ID and the token are required; the token alone cannot authenticate.
• Check that the token has not been deleted in PlanetScale's settings.
• Make sure the token has organization read access.

"Multiple PlanetScale organizations are reachable" error

• The credentials can reach more than one organization, so name the one to connect.
• Connecting via OAuth in the console, pick the organization when prompted after authorizing.
• Connecting via the API, set the organization field to the organization name.

Missing resources

• PlanetScale can take a few minutes to sync everything.
• Trigger a manual Sync from the account header to refresh.

Disconnecting

Disconnect the account in Polylane, then delete the service token from your PlanetScale organization settings.

Connecting PlanetScale needs no browser: the same endpoint the console calls fits in a CI job. One authenticated POST creates the connection and starts the first sync.

Prerequisites

• A Polylane API key with the cloud_accounts:write and cloud_accounts:read scopes. See API keys and OAuth.
• Your workspace ID, which starts with ws_. Read it from GET /v1/workspaces with the same key.
• A PlanetScale service token pair from your organization's Settings → Service tokens, with organization read access (e.g. read_databases, read_branches). The console's OAuth flow needs a browser; service tokens do not.

Create the connection

curl -X POST https://api.polylane.com/v1/cloud_accounts \
  -H "x-api-key: $POLYLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "planetscale",
    "workspaceId": "ws_0abc123",
    "tokenId": "<service-token-id>",
    "token": "<service-token>",
    "organization": "my-org"
  }'

One call connects one PlanetScale organization.

• organization may be omitted only when the token reaches exactly one organization; otherwise the call fails with a 400 that lists the reachable organization names.

The response lists what was connected, with the first sync already running. Trimmed to the two fields the rest of the flow reads:

{
  "success": true,
  "result": {
    "provider": "planetscale",
    "accounts": [{ "id": "acc_34gky74ibc92h8t2efn8csrh", "status": "syncing" }],
    "failures": []
  }
}

An account that is already connected lands in failures instead of accounts, so repeating the call never duplicates a connection.

Wait for the first sync

Poll each returned account by its id until status reaches ready (new on registration, syncing while resources stream in):

until [ "$(curl -s "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY" | jq -r '.result.status')" = "ready" ]; do
  sleep 15
done

Give the loop a deadline so a failed connect fails the job instead of hanging it. Once the account is ready, its resources are in the topology and Polylane has started its first check.

Disconnect from the API

Deleting the connection stops every sync and check and deletes the credentials Polylane held. The call needs the cloud_accounts:delete scope:

curl -X DELETE "https://api.polylane.com/v1/cloud_accounts/$WORKSPACE_ID/$ACCOUNT_ID" \
  -H "x-api-key: $POLYLANE_API_KEY"

Then revoke the PlanetScale credential on the provider side, as described under Disconnect below.