Skip to main content

​
Overview

Creating an OAuth application within PlanetScale allows your application to access your users’ PlanetScale accounts. With PlanetScale OAuth applications, you can choose what access your application needs, and a user will allow (or deny) your application those accesses on their PlanetScale account. The organization that you create the OAuth application in is the “owner” of the application.

​
Getting started

​
1. Creating an OAuth application in PlanetScale

  1. To create a new OAuth application, log into your organization and click Settings > OAuth applications.
  2. Create a new OAuth application by clicking Create new application.
  3. You will need to fill out the following fields:
  • Name: A user-friendly name for your OAuth application.
  • Domain: The full URL to your application’s domain.
  • Redirect URI: The full URL PlanetScale should redirect users on completion of the authorization flow, also known as the callback URL. It must have the same domain as the domain above.
  • Avatar: An image that represents your OAuth application. (Optional but recommended.)
You will also be agreeing, on behalf of your organization, to prominently display a privacy policy and obtain consent to your organization’s terms of use from all users of your products and services.

​
2. Credentials to copy to your application code

Once you have created your OAuth application in PlanetScale, you will need the following credentials to use the OAuth authorization flow:
  • ID: Your OAuth application’s ID.
  • Client ID: Your OAuth application’s client ID.
  • Redirect URL: The full URL PlanetScale should redirect users on completion of the authorization flow, also known as the callback URL.
  • Client secret: Your OAuth application’s client secret, used to exchange authorization codes for access tokens. (This will only be shown once, make sure to save it!)
Later in this document, we will go through how you use each of these credentials. We recommend saving them as environment variables.

​
3. OAuth application access scopes

Every OAuth application in PlanetScale will request from its users a specific set of permissions in the users’ databases. We call these permissions “access scopes.” They are broken into:
  • User access
  • Organization access
  • Database access
  • Branch access
Access is scoped to a resource. For example, selecting write_branches on an organization allows you to write branches across all databases in organizations the user gives permission to, while write_branches on a database enables you to only write branches in databases the user gives permission to. The API reference for each endpoint will say what scope is needed. In this step, select the access scopes you think your application will need on a user’s account and click the Save access scopes button.