Introducing the PlanetScale API and OAuth applications

By Frances Thai, Taylor Barnett | January 31, 2023

Today, we are releasing a new way to manage your PlanetScale databases programmatically: The PlanetScale API.

The API opens up new ways to interact with PlanetScale through automation and other developer tools, like CI/CD, infrastructure as code, deployment tools, and application platforms. Alongside the PlanetScale web app and CLI, the PlanetScale API allows you to closely integrate PlanetScale branches, deploy requests, passwords, and other features into your existing workflow.

In addition to the API, we are also launching OAuth applications in limited beta. OAuth applications alongside the PlanetScale API enable your users to interact with their PlanetScale databases from your application.

PlanetScale API

Through the PlanetScale API, users can do simple tasks like updating and creating databases, as well as more complex tasks like managing the lifecycle of a deploy request.

If it can communicate via HTTP, it can be integrated with the PlanetScale API. For example, you can:

• Automatically create and delete database branches from CI/CD pipelines or data migration tooling
• Programmatically build out new environments that connect to PlanetScale database branches for testing
• Get information about a PlanetScale user, database, branch, organization, and deploy request
• Check the status of deploy requests in the deploy queue
• Automate creating and deleting database connection strings for internal users or tools
• Create, update, approve, deploy, and delete deploy requests programmatically from tooling outside of PlanetScale

By making these actions accessible through the API, it will empower you to automate processes and create powerful workflows that will ultimately drive faster and richer developer experiences with PlanetScale.

Using the PlanetScale API

Authorization

To get started with the PlanetScale API, you only need to create a service token, and grant it access based on the endpoints you want to use in the API. The accesses a service token needs to use are described in each endpoint's documentation.

For further instructions on using the PlanetScale API with a service token, refer to our service tokens API documentation.

Requests and responses

Once you have a service token, you can fill out the request parameters in the API reference and copy and paste code directly from the documentation:

OAuth applications

Take the PlanetScale API one step further with PlanetScale OAuth Applications. OAuth applications enable you to seamlessly integrate your platform with PlanetScale, and allow your users to give granular PlanetScale account access to your platform in return.

Enrolling in the limited beta

If you are interested in creating your own PlanetScale OAuth application, you can enroll on the waitlist through your PlanetScale organization's Settings > Beta features page. Once we've received your enrollment request, a PlanetScale team member will be in touch about your OAuth use case.

Refer to our OAuth documentation for further instructions on creating an OAuth application and completing our authorization flow.

PlanetScale API + OAuth application demo

We've created a Next.js-based demo called PlanetPets that uses PlanetScale OAuth and API to access users' organizations, databases, branches, and create new branches. The user's organizations are then presented as "gardens" where their databases are "trees." Within PlanetPets, users can water their "trees" to grow new branches.

This sample app shows you how to implement OAuth authentication with PlanetScale in a Next.js application. Set it up yourself using the code in the PlanetPets GitHub repo, or play around with the PlanetPets live demo.

PlanetScale integration examples

Two fantastic community partners have already built integrations using the powerful combination of OAuth applications and the PlanetScale API. These integrations are available for use today.

Netlify

Netlify is launching a new PlanetScale integration into Netlify Labs. Netlify's new integration allows Netlify users to closely integrate PlanetScale branches, deploy requests, passwords, and other features into the Netlify workflow. Additional benefits for Netlify users include more easily connecting PlanetScale databases to Netlify sites, assigning database branches to different deploy contexts, and using the withPlanetScale function in Netlify Functions to seamlessly insert a connection into the database call. You can read more about the integration in the Netlify integration docs.

Resmo

Resmo uses an OAuth application and the PlanetScale API to connect to PlanetScale in a few clicks to bring asset visibility, continuous security, and compliance of PlanetScale databases to their users. Resmo collects directory assets like databases, organizations, and database branches from users' PlanetScale accounts through the API for users to query and set up custom security rules to automate security checks. You can read more about the integration in the Resmo integration docs.

Feedback

We can't wait to see what you'll build with the new PlanetScale API and OAuth applications! If you have feedback on your experience using the API, we would love to hear it. You can open up a new discussion topic in the PlanetScale discussion repo with your feedback.