Skip to content

Service tokens

Create service tokens for your PlanetScale organization.

Service tokens

PlanetScale provides the ability to create service tokens for your PlanetScale organization via the CLI or directly in the UI.

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

Create service tokens using the PlanetScale UI

Create a new service token

  1. Go to your organization settings page for service tokens: app.planetscale.com/<org>/settings/service-tokens

Service token settings pageService token settings page

  1. Click on the "New service token" button

This will open a pop-up modal that prompts you to name the service token.

New service token pop-up modalNew service token pop-up modal

  1. Once you have provided a name for the service token, click "Create service token" to finish creating the token.

  2. Copy the token value from the UI.

Service token detail pageService token detail page

You will need both the token ID and the token value to connect to your databases.

Copied
PLANETSCALE_SERVICE_TOKEN_NAME=your-token-id
PLANETSCALE_SERVICE_TOKEN=your-token-value
Tip
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.

Add database access permissions

  1. Click "Add database access" to select the database access permissions for the token.

Database access permissions pop-up modalDatabase access permissions pop-up modal

For each database you add, you have the ability to select from the following permissions:

  • create_branch
  • read_branch
  • delete_branch
  • connect_branch
  • connect_production_branch

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

  1. Once you have selected the access permissions, click "Save permissions" to save your selection.

You can add access to another database in your organization by clicking on the "Add database access" a second time.

Manage database access permissions

  1. Go to the service tokens page for your organization: app.planetscale.com/<org>/settings/service-tokens
  2. Click on the service token ID for the service token you would like to update.
  3. Click on the blue link "Manage permissions" underneath the database name and permissions to add or remove access permissions.

Manage PermissionsManage Permissions

  1. Adjust the permissions in the pop-up modal and then click "Save permissions" to update the database access permissions.

To remove all access permissions for a database, click on the "Remove Access" button associated with the database you would like to remove. Click "delete" to remove all access for the database.

Delete a service token

You can delete a service token at any time from the service token detail page.

  1. Go to the service tokens page for your organization: app.planetscale.com/<org>/settings/service-tokens
  2. Click on the service token ID for the service token you would like to delete.
  3. Click on the "Delete service token" button in the upper right hand corner.
  4. Confirm deletion by clicking the "Delete" button in the pop-up modal.

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

Create service tokens using the PlanetScale CLI

Use the PlanetScale CLI to create and manage service tokens for your PlanetScale organization.

Create a new service token

Use the following command to create a service token:

Copied
pscale service-token create

This command will return a service token name 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:

Copied
pscale service-token add-access <token id> <access permission> --database <database name>

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

Copied
pscale service-token add-access <token id> read_branch delete_branch create_branch --database <database 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:

Copied
pscale service-token delete-access <token id> <access permission> --database <database name>

Delete a service token

To delete a service token, run the following command:

Copied
pscale service-token delete <token id>

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

Was this page useful?
Last updated on November 18, 2021
Help us improve this page
PrivacyTerms© 2021 PlanetScale Inc.