PlanetScale API tokens are your keys to unlocking programmatic control over your PlanetScale databases, allowing you to automate tasks like schema changes, data imports, or custom reporting.
Here’s a look at a PlanetScale API token in action, managing a database branch:
# List branches for a database
curl "https://api.planetscale.com/v1/organizations/my-org/databases/my-database/branches" \
-H "Authorization: Bearer my-api-token"
# Output might look like:
# {
# "data": [
# {
# "id": "br_abc123",
# "name": "main",
# "created_at": "2023-10-27T10:00:00Z",
# "updated_at": "2023-10-27T10:00:00Z"
# },
# {
# "id": "br_def456",
# "name": "develop",
# "created_at": "2023-10-27T10:05:00Z",
# "updated_at": "2023-10-27T10:05:00Z"
# }
# ],
# "next_page_token": null
# }
# Create a new branch
curl -X POST "https://api.planetscale.com/v1/organizations/my-org/databases/my-database/branches" \
-H "Authorization: Bearer my-api-token" \
-H "Content-Type: application/json" \
-d '{"name": "feature-branch", "source_branch": "develop"}'
# Output might look like:
# {
# "id": "br_ghi789",
# "name": "feature-branch",
# "created_at": "2023-10-27T11:00:00Z",
# "updated_at": "2023-10-27T11:00:00Z",
# "parent_branch_id": "br_def456"
# }
The core problem PlanetScale API tokens solve is enabling secure, automated interaction with your PlanetScale infrastructure without requiring manual intervention or storing sensitive user credentials in your applications. This is crucial for CI/CD pipelines, automated provisioning, and integration with other services.
Internally, PlanetScale’s API uses these tokens to authenticate your requests. When you include an Authorization: Bearer <your-api-token> header, the PlanetScale API server validates the token against its internal registry. If valid and possessing the necessary scopes, the request is processed. The token itself is a long, random string, and its security relies on keeping it secret and managing its permissions carefully.
The primary levers you control are the token’s name (for identification), its scopes (which dictate what actions it can perform), and its expiration date (for security).
When creating a token, you’ll see options for scopes. These are critical. A token with read_only scope can only fetch information. A token with schema_changes scope can create and alter database schemas but cannot delete data. A token with database_access scope can perform full CRUD operations on your data. The most permissive scope is admin, which grants full control over an organization’s resources. Always grant the least privilege necessary for the task.
The expiration field is equally important. By default, tokens might have a long lifespan, but for sensitive operations or tokens used by external services, setting a shorter expiration (e.g., 2024-01-01T00:00:00Z) significantly reduces the risk if a token is compromised. You can also set expires_at to null for a token that never expires, but this is generally discouraged for security reasons.
Most people focus on the token’s value and its scopes, but the organization_id and database_name implicitly associated with a token (or specified in the API call) are also part of the access control logic. A token might have schema_changes scope, but if the API call doesn’t specify a database_name that the token is authorized for, the request will still fail. This granular control ensures that even a broadly scoped token can be confined to specific resources.
The next step is understanding how to integrate these tokens into your deployment workflows using tools like Terraform or Pulumi.