Create an application for the API
In this article:
To create an application for general use, you'll need to build a Redirect URI handler to generate access tokens for each of your users. However, if you only want to use the API on your own Gumroad account, you can manually generate an access token, which is a simpler process.
For just your account
If you're writing some custom code you need to run with your Gumroad account, all you need is an access token. Your access token is used in the request header of every request to the API and should be kept secret, like a password.
Generating an access token
First, sign in to your Gumroad account. Then, go to advanced settings. Here, you'll see a form to create a new application.
Provide the following information and click "Create application":
- Application icon: A small thumbnail image to identify your application.
- Application name: A name for your application
- Redirect URI: While this is very important when making a general-purpose application, when you just want an access token to use the API with your own account, simply enter localhost (http://127.0.0.1) in this field, as its value is not meaningful.
Keep the application ID and secret values safe and confidential, but they are not necessary for manually generating an access token. Instead, use the "Generate access token" button to get your access token.
Keep your access token safe and confidential, like a password. When you make an API call, include it in the request's header. Here's an example of a request with the access token (replace ACCESS_TOKEN with the string from your application):
curl https://api.gumroad.com/v2/products \
-d "access_token=ACCESS_TOKEN" \
-X GET
You can always edit your application or find your Access Token again through the advanced settings page.
While we also provide a refresh_token when authenticating a user, we do not expire the access_token until it is revoked manually.
With your access token in hand, head back to our API documentation for a list of endpoints the API makes available.
For any Gumroad account
Setting up an application to use with any account starts off with the same process: creating an application through the advanced settings page.
Again, you'll need an Application icon, Application name, and Redirect URI. Now, when creating an application for any Gumroad account, the Redirect URI is actually important. To explain why, we must first detour to "Sign in with Gumroad."
Sign in with Gumroad
If your website is built on Ruby on Rails, you can use the Gumroad Omniauth gem to enable "Sign in with Gumroad" in your software. Otherwise, use whatever OAuth/OmniAuth library your framework of choice supports. You will be provided with an Application ID (aka client_id ) and Application Secret (aka client_secret ) to use in the authentication process.
Here is a step-by-step example:
- From the third-party app, send the user to Gumroad for authorization using a URL like this:
https://gumroad.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE
2. Replace CLIENT_ID, REDIRECT_URI, and SCOPE with the correct values. Here's a sample URL:
3. Get the temporary authorization code from the URL redirected from Gumroad after authorization. For example, after authorization, Gumroad would redirect the user to the configured redirect_uri, something like this:
4. Use that code with client_id and client_secret to send an HTTPS request to Gumroad (as shown in the curl example) to get the access_token. We can then use this access_token in all API requests. Here is an example of getting that token:
curl --request POST \
--url https://api.gumroad.com/oauth/token \
--data code=c302a5e2330ea9a581e370c9c7c9b87760734336ae3253d37e5425a9aa1a04d9 \
--data client_id=f74e4939f6f9efe74f85ff034af9e9e04540d1e8fce609d652715db5480d4dbe \
--data client_secret=10173a92c55744b097f0e2a1c4ea03d9dd5b54ad04c82e8efaabbec2d3a8f1f6 \
--data redirect_uri=https://oauthdebugger.com/debug
{"access_token":"abf11e4ab2850ffd50ef690257f7a1c998a443059513d1a4826f2b3159620505","token_type":"Bearer","refresh_token":"77d7836232246508a6c5b1a9d153d8edbce74249edafaef228554e7be8a29b5e","scope":"edit_products","created_at":1609038258}
Using a Redirect URI
The Redirect URI can be any endpoint on your website. After a user authenticates through a "Log in with Gumroad" button, Gumroad will redirect them back to the configured Redirect URI with a temporary authorization code. The application can then use that temporary code along with the Application ID and Application Secret to get an access token for that user.
You can change your Redirect URI at any time.
Enabling your application
Following the OmniAuth library's documentation, configure your Application ID and Application Secret, and then make sure you store the Access Tokens that the system generates appropriately for each user during the Redirect URI step. Each of these values should be treated like passwords, kept secret and safe.