Skip to main content

​
Overview

Service tokens provide an alternate authentication method to be used with the PlanetScale CLI and API. They are typically used in automated scenarios where pscale auth login cannot be used. Service tokens are also required for any calls to the API, as well as minting OAuth tokens for API use.

​
Create service tokens using the PlanetScale dashboard

To create a service token using the dashboard, log into your organization, go to the “Settings” > “Service tokens” page, and click the “New service token” button. Give the token a name (this is used for your reference only) and click “Create service token”. The modal will update, displaying your service token where the Name field was. Copy the ID and token values as you’ll need them moving forward. Click “Edit token permissions” to proceed.
Be sure to copy the service token after you create it. There’s no way to retrieve the token value once you leave this page.
Service token detail page

​
Assign service token permissions

Service tokens are configured with granular permissions, both for the organization that owns them as well as on a per database level. Before you can use a service token, these permissions must be added.

​
Add organization permissions

Organization permissions are required when performing operations that are specific to the organization and not for an individual database. To enable a service token for performing these operations, locate the Organization access section and click “Add organization permissions”. In the Organization access permissions modal, check the box next to each of the permission scopes that you want to assign to the token. Click “Save permissions” once finished. For a full list of organization access permissions, see the API documentation for service tokens.

​
Add database permissions

In order to perform operations specific to a database, permissions can be assigned per-database. To do this, locate the section titled Database access and click “Add database access” to open the Database access permissions modal. Select the database you want to grant access to and check the box next to each permission option you need to grant. Once you are done, click “Save permissions”. For a full list of database access permissions, see the API documentation for service tokens.
The Database access permissions modal.

​
Add permissions for all databases

Organization admins can grant database permissions to all current and future databases. This is available in the Permissions for all databases section. Any permission added to all databases will not be able to be disabled on an individual basis.

​
Creating databases with service tokens

A service token with the create_databases organization permission can create new databases in your organization. When a service token creates a database, it is automatically granted database access permissions for that database. You do not need to add database permissions separately for each database the token creates. Only organization administrators can grant the create_databases permission to a service token. Auto-granted permissions apply only to databases the token creates, not to existing databases in the organization. To grant this permission from the dashboard, open the service token’s Organization access section and click “Add organization permissions”. In the Organization access permissions modal, check the box for Create organization databases and click “Save permissions”. You can also grant organization access using the CLI:
Once the create_databases permission is in place, you can create databases with the token using the CLI or API. Refer to the Create a database API reference for all available parameters.

​
Service tokens and deploy requests approvals

When a database requires administrator approval for deploy requests (located in your database’s Settings page), a service token cannot approve a deploy request created by the same service token. Also, users can’t approve a deploy request created by a service token that they created.

​
Use a service token with the PlanetScale CLI

To use service tokens with the PlanetScale CLI, set the following environment variables in your terminal:
When you execute commands using the PlanetScale CLI, it will automatically parse those values and use them to access the service. However, you’ll also need to pass in your organization name using the --org flag like so:
If you don’t want to set environment variables, you may also pass in the Service Token and Service Token ID by using the --service-token and --service-token-id flags respectively:

​
Use a service token with the PlanetScale API

In order to execute a request to the PlanetScale API, you’ll need a service token to execute requests directly or for minting OAuth tokens. Both the ID and token are required in the Authorization header without a scheme. Below is an example of how to use a service token to list details about the organizations the token can access:
Refer to the API docs for more details on how to use the API.

​
Modify service token permissions

If you want to modify the permissions granted to a service token, start by opening the service token from the settings pane. Select the three dots next to the organization or database name permissions you want to modify and click “Edit permissions”.
The location of the Edit permissions option for organization permissions.
This will open a modal that allows you to modify the permissions the service token has to access that organization.

​
Delete a service token

You can delete a service token at any time from the service token detail page. Simply click the “Delete service token” button.
Delete service token.

​
Manage service tokens using the PlanetScale CLI

Service tokens can also be created and managed directly from the PlanetScale CLI.

​
Create a new service token

Use the following command to create a service token:
This command will return a service token ID and value for your use.

​
Add database access permissions

You can add database access permissions to your service token for each database in your organization. To add database access permissions, use the command:
For example, to give a service token the ability to create, read, and delete branches on a specific database, use the following command:
A complete list of service token access permissions can be found in the PlanetScale API documentation.

​
Remove database access permissions

You can also remove database access permissions for a service token. Use the following command to remove one or more permissions:

​
Delete a service token

To delete a service token, run the following command:

​
Service token automation

Running pscale in CI or an AI agent uses a service token instead of pscale auth login. Provide the token as environment variables (recommended) or as flags on each command; both are equivalent:
A service token has no active organization, so resource commands need the org supplied explicitly. Set it with PLANETSCALE_ORG, the --org flag on the subcommand, or pscale org switch <org> (which works with a service token):
--org goes on the resource subcommand (database, branch, sql, api, …), never on root pscale. pscale --org <org> database list fails with unknown flag: --org.
Per-command-family matrices (env-var auth, --service-token flag, required --org, Postgres/Vitess, --format json, API equivalent): org · service-token · database · branch · role · password.

​
Commands to avoid under a service token

Do not retry these with service-token auth. The failure is by design, not transient. This is the most common cause of agent retry loops.
pscale org show prints not authenticated yet. Please run 'pscale auth login' under a valid service token. This is the no-current-org state, not an auth failure. Do not respond by running pscale auth login. Discover the org with pscale org list and pass it with --org or PLANETSCALE_ORG.
pscale auth check --format json confirms a token is wired up. Expect "authenticated": true, "auth_method": "service_token", and (until an org is set) an action_required status with a NO_ORG issue and a non-zero exit code. Resolve it by passing --org/PLANETSCALE_ORG on your commands.

​
pscale api fallback for hard-to-parse output

When a command’s human output is hard to parse, prefer --format json, or drop to the raw API with pscale api, which returns the API response verbatim and uses the same token:

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.