Skip to content

Service tokens

Learn how to work with service tokens, an alternate way to autheticate with PlanetScale using the CLI.


PlanetScale provides the ability to create service tokens for your PlanetScale organization via the CLI or directly in the UI. Service tokens provide an alternate authentication method to be used with the PlanetScale CLI and are typically used in automated scenarios where pscale auth login cannot be used.


Service tokens are not recommended for connecting to production databases. Instead, connect securely to your database using PlanetScale connection strings.

Create service tokens using the PlanetScale dashboard

To create a service token using the dashboard, log into your organization and click "Settings" > "Service tokens" > "New service token".

Service token settings page

Give the token a name (this is used for your reference only) and click "Create service token".

New service token pop-up modal

The modal will update, displaying your service token where the Name field was. Copy the token and 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

Copy the ID of the service token as it is required to use the service token with the CLI.

Service tokens are configured with granular permissions per database. Before you can use a service token, these permissions must be added. Click "Add database access" to open the Database access permissions modal.

The service token configuration view.

Select the database you want to grant access for and check the box next to each permission option you need to grant. Once you are done, click "Save permissions".

The Database access permissions modal.

Your service token is now configured for use with the PlanetScale CLI.

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:

pscale branch create <DB_NAME> <BRANCH_NAME> --org <ORG_NAME>

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:

pscale branch create <DB_NAME> <BRANCH_NAME> --org <ORG_NAME> --service-token <SERVICE_TOKEN> --service-token-id <SERVICE_TOKEN_ID>

Modify service token database permissions

If you want to modify the permissions granted to a service token for a specific database, open the service token from the settings pane and click "Manage permissions" for the database permissions you want to modify.

The location of the Manage permissions option.

This will open a modal that allows you to modify the permissons the service token has to access that database.

The Database access permissions modal while modifying permissions.

To remove access to a database entirely, click "Remove access" on the line for that database.

Remove database access for a service token.

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.

Deleting a service token will sever any database connections that use the given service token.

Manage service tokens using the PlanetScale CLI

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

Create a new service token

Use the following command to create a service token:

pscale service-token create

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:

pscale service-token add-access <SERVICE_TOKEN_ID> <ACCESS_PERMISSION> --database <DB_NAME>

For example, to give a service token the ability to create, read, and delete branches on a specific database, use the following command:

pscale service-token add-access <SERVICE_TOKEN_ID> read_branch delete_branch create_branch --database <DB_NAME>

A complete list of service token access permissions can be found here.

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:

pscale service-token delete-access <SERVICE_TOKEN_ID> <ACCESS_PERMISSION> --database <DB_NAME>

Delete a service token

To delete a service token, run the following command:

pscale service-token delete <SERVICE_TOKEN_ID>

Deleting a service token will sever any database connections that use the given service token.

Need help?

Get help from the PlanetScale support team, or join our GitHub discussion board to see how others are using PlanetScale.

Was this page useful?
Last updated on September 1, 2022
Help us improve this page
© 2022 PlanetScale Inc.