Service tokens

Using service tokens with the PlanetScale API.

Overview

This document will show you how to create a service token for the API in PlanetScale. All PlanetScale API endpoints require one. You can read more about using service tokens outside of the API in the PlanetScale service token documentation.

Authorization header

To make requests to the API, add the service token values in theAuthorization header in your HTTP API request using the following format:

Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>

Here is a cURL example:

curl --request GET 'https://api.planetscale.com/v1/organizations' \
--header 'Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>'

Creating a service token

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

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

Service token ID

Copy this value to use as SERVICE_TOKEN_ID.

The ID is also visible on the service token page after you continue to token permissions.

Service token

The token is generated immediately after the service token is created.

Copy this value to use as SERVICE_TOKEN.

972

Modal showing service token ID and token secret

Access permissions

You can access your specific service token page from your organization's Settings > Service token page.

Service tokens are configured with granular permissions for both organizations and databases access. On the page for your specific service token you can add one or many of the following permissions.

2080

Showing the UI for organization and database access with buttons to add what access permissions.

Please note that you may only add service token accesses that you are also authorized to do. For example, as an organization member, you can't create a service token with create_databases access.

Organization access permissions

A service token can have granular permissions across an organization with one or multiple of the following access permissions.

Check the box next to each permission option you need to grant. Once you are done, click Save permissions.

Access permissionsDescription
read_organizationGet information about an organization and its regions
read_databasesGet information about an organization's databases, their deploy requests, promotion requests, and regions
create_databasesCreate organization databases
delete_databasesDelete organization databases
read_oauth_applicationsGet information about an organization's OAuth applications and their tokens
write_oauth_tokensCreate and refresh OAuth grants and tokens for an OAuth application
read_oauth_tokensGet OAuth tokens for an OAuth application
delete_oauth_tokensDelete OAuth tokens for an OAuth application

Database access permissions

A service token can have granular permissions across a database with one or multiple of the following access permissions.

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.

Access permissionsDescription
read_databaseGet information about a database
write_databaseUpdate information about a database
delete_databaseDelete a database
create_branchCreate a database branch
read_branchRead a database branch
delete_branchDelete a database branch
delete_production_branchDelete a production database branch
connect_branchConnect to a database branch
connect_production_branchConnect to a production database branch
delete_branch_passwordDelete a password for a non-production branch
delete_production_branch_passwordDelete a password for a production branch
create_deploy_requestCreate a deploy request
read_deploy_requestRead a deploy request
approve_deploy_requestApprove a deploy request
create_commentCreate a deploy request comment
read_commentRead a deploy request comment
read_backupsList backups
write_backupsCreate and update backups
delete_backupsDelete development branch backups
delete_production_branch_backupsDelete production branch backups
restore_backupRestore a development branch backup
restore_production_branch_backupRestore a production branch backup

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.

Example

Creating a PlanetScale branch with service tokens

Creating a database branch is one of the many API endpoints documented in our PlanetScale API docs.

The following steps are required to make a successful API request:

  1. Create a service token as described at the top of this page. Make sure to copy and paste the service token ID and service token somewhere safe.
  2. You need to make sure your service token has the correct access permissions. Each endpoint documentation describes the service token access permissions it needs in the Authorization section. For example, in the create a branch endpoint you will need to grant the service token the create_branch access for your database:
  1. After your permissions are set, you can now use the service token in a cURL request:
curl --request POST \
     --url https://api.planetscale.com/v1/organizations/ORGANIZATION_NAME/databases/DATABASE_NAME/branches \
     --header 'Authorization: SERVICE_TOKEN_ID:SERVICE_TOKEN' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     --data '{"name": "BRANCH_NAME","parent_branch": "PARENT_BRANCH_NAME"}'

Make sure to fill in the ORGANIZATION_NAME, DATABASE_NAME, BRANCH_NAME, PARENT_BRANCH_NAME, SERVICE_TOKEN_ID, and SERVICE_TOKEN variables.

  1. You will get a response with the following data, as described in the specific API endpoints documentation:
{
  "id": "xsvewamrebwz",
  "type": "Branch",
  "name": "new-feature",
  "created_at": "2023-01-10T23:31:01.573Z",
  "updated_at": "2023-01-10T23:31:01.573Z",
  "restore_checklist_completed_at": null,
  "access_host_url": "xsvewamrebwz.us-east-1.psdb.cloud",
  "schema_last_updated_at": "2023-01-10T23:31:01.573Z",
  "mysql_address": "us-east.connect.psdb.cloud",
  "mysql_provider_address": "aws.connect.psdb.cloud",
  "initial_restore_id": null,
  "mysql_edge_address": "aws.connect.psdb.cloud",
  "ready": false,
  "production": false,
  "sharded": false,
  "shard_count": 0,
  "actor": {
    "id": "g2dr4sbhz6ag",
    "type": "User",
    "display_name": "Taylor Barnett",
    "avatar_url": "https://www.gravatar.com/avatar/2a44999e8816311f19eea3d7516d9204?d=https%3A%2F%2Fapp.planetscale.com%2Fgravatar-fallback.png&s=64"
  },
  "restored_from_branch": null,
  "html_url": "https://app.planetscale.com/taylorhackyplace/example-test/new-feature",
  "url": "https://api.planetscale.com/v1/organizations/taylorhackyplace/databases/example-test/branches/new-feature",
  "region": {
    "id": "kc0e1ij8juzp",
    "type": "Region",
    "provider": "AWS",
    "enabled": true,
    "public_ip_addresses": [
      "23.23.187.137",
      "52.6.141.108",
      "52.70.2.89",
      "50.17.188.76",
      "52.2.251.189",
      "52.72.234.74",
      "35.174.68.24",
      "52.5.253.172",
      "54.156.81.4",
      "34.200.24.255",
      "35.174.79.154",
      "44.199.177.24"
    ],
    "display_name": "AWS us-east-1",
    "location": "Northern Virginia",
    "slug": "us-east"
  },
  "multiple_admins_required_for_demotion": false,
  "parent_branch": "main"
}

Potential errors

If you get a {"code":"not_found","message":"Not Found"} response, it is likely you either did not change the variables in the example cURL request or you did not set the access permissions correctly for the service token.