Planetscale.ServiceToken reference

ServiceToken

Source: packages/planetscale/src/ServiceToken.ts

A PlanetScale API service token with exactly the declared permissions on one database.

The deployment identity must be allowed to create service tokens and manage their accesses. These API credentials are separate from database passwords.

PlanetScale returns the secret only at creation. Alchemy preserves it in state; use a state backend that protects secrets. Existing tokens cannot be adopted because their secret cannot be recovered.

Service tokens carry no labels or tags, so a token’s physical name, which holds this resource’s instance ID, is its only ownership marker. If a create is interrupted before Alchemy saves the token, the next destroy finds it by that name and revokes it, and the next deploy revokes it and mints a replacement, since its secret was never saved. list returns nothing: a name alone can’t prove which stack made a token, and listing every token would offer an organization’s other tokens to account-wide cleanup.

Changing the name prefix, organization, or database creates a replacement. Resources that consume the token’s outputs are updated before Alchemy deletes the previous token. Changes to accesses are reconciled in place.

ServiceToken: Creating a Database Token

Token for a database declared in the stack

const database = yield* Planetscale.MySQLDatabase("Database", {
  clusterSize: "PS_10",
});

const token = yield* Planetscale.ServiceToken("Sync", {
  database,
  accesses: ["read_database", "write_database"],
});

Token for a Postgres database

const database = yield* Planetscale.PostgresDatabase("Database", {
  clusterSize: "PS_10",
});

const token = yield* Planetscale.ServiceToken("Backups", {
  database,
  accesses: ["read_backups", "write_backups"],
});

Token for an existing database by name

const token = yield* Planetscale.ServiceToken("Sync", {
  database: "app-db",
  accesses: ["read_database"],
});

ServiceToken: Referencing a Database from Another Stack

const database = yield* Planetscale.MySQLDatabase.ref("Database", {
  stack: "shared-data",
});

const token = yield* Planetscale.ServiceToken("Sync", {
  database,
  accesses: ["read_deploy_request", "create_deploy_request"],
});

ServiceToken: Rotating a Token

// Changing `name` creates a new token; consumers are updated
// before the previous token is revoked.
const token = yield* Planetscale.ServiceToken("Sync", {
  name: "sync-2026-11",
  database,
  accesses: ["read_database"],
});