Skip to main content

​
Overview

The Gumroad API uses OAuth 2.0 for authentication, implemented via the Doorkeeper gem. This allows you to securely access the API on behalf of Gumroad users.
All API requests must be authenticated using an access token obtained through the OAuth 2.0 flow.

​
OAuth 2.0 Flow

Gumroad supports three OAuth 2.0 grant types:
  1. Authorization Code - For web applications
  2. Password Credentials - For trusted applications
  3. Client Credentials - For application-level access

​
Authorization Code Flow

This is the most common flow for web applications:

​
Step 1: Register Your Application

First, register your application at: 
https://gumroad.com/settings/applications
You’ll receive:
  • Client ID - Your application identifier
  • Client Secret - Your application secret (keep this secure!)

​
Step 2: Redirect User to Authorization URL

Redirect the user to Gumroad’s authorization endpoint: 
https://gumroad.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=REQUESTED_SCOPES
​
client_id
string
required
Your application’s client ID
​
redirect_uri
string
required
The URL to redirect to after authorization (must match registered URI)
​
response_type
string
required
Must be code for authorization code flow
​
scope
string
required
Space-separated list of scopes (see Scopes below)
​
state
string
Optional CSRF protection token

​
Step 3: Exchange Code for Access Token

After the user authorizes your application, they’ll be redirected to your redirect_uri with a code parameter: 
https://your-app.com/callback?code=AUTHORIZATION_CODE
Exchange this code for an access token: 
curl -X POST https://gumroad.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

​
Token Response

{
  "access_token": "abc123def456...",
  "token_type": "Bearer",
  "expires_in": null,
  "refresh_token": "xyz789uvw...",
  "scope": "edit_products view_sales",
  "created_at": 1704153600
}
Gumroad access tokens do not expire (expires_in: null), but refresh tokens are still provided for future compatibility.

​
Password Credentials Flow

For trusted applications, you can use the password flow to authenticate with username/password: 
curl -X POST https://gumroad.com/oauth/token \
  -d "grant_type=password" \
  -d "username=USER_EMAIL_OR_USERNAME" \
  -d "password=USER_PASSWORD" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
The password flow should only be used by trusted first-party applications. For third-party integrations, always use the authorization code flow.

​
Using Access Tokens

Once you have an access token, include it in all API requests using the Authorization header: 
curl https://api.gumroad.com/v2/user \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Using the Authorization: Bearer header is the preferred method for authentication as it keeps tokens out of URLs and server logs.

​
Scopes

Scopes control what your application can access. When requesting authorization, specify the scopes you need:
​
view_public
string
default:true
View public profile information (default scope)
​
view_profile
string
View detailed profile information
​
edit_products
string
Create, update, and delete products
​
view_sales
string
View sales data and customer information
​
view_payouts
string
View payout information
​
mark_sales_as_shipped
string
Mark sales as shipped with tracking information
​
refund_sales
string
Process refunds for sales
​
edit_sales
string
Edit sales, resend receipts, and perform other sale operations
​
revenue_share
string
Access revenue share information
​
ifttt
string
Integration with IFTTT (special scope)

​
Requesting Multiple Scopes

Request multiple scopes by separating them with spaces: 
https://gumroad.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=edit_products%20view_sales%20mark_sales_as_shipped
The mobile_api, creator_api, unfurl, and helper_api scopes are reserved for internal use and not available to public applications.

​
Refresh Tokens

Although Gumroad access tokens don’t expire, you can use refresh tokens to obtain new access tokens: 
curl -X POST https://gumroad.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

​
Token Management

Users can manage authorized applications at: 
https://gumroad.com/settings/authorized_applications
When a user revokes access, your access token will become invalid.

​
Testing Authentication

Test your access token by fetching the authenticated user: 
curl https://api.gumroad.com/v2/user \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Successful response: 
{
  "success": true,
  "user": {
    "id": "user_id",
    "email": "[email protected]",
    "name": "Creator Name",
    "bio": "Creator bio...",
    "url": "https://gumroad.com/creator"
  }
}

​
Security Best Practices

Never commit or expose your client secret or access tokens in public repositories or client-side code.
  1. Store credentials securely - Use environment variables or secure vaults
  2. Use HTTPS only - Never send tokens over unencrypted connections
  3. Implement CSRF protection - Use the state parameter in OAuth flows
  4. Validate redirect URIs - Ensure redirect URIs match exactly
  5. Rotate secrets regularly - Periodically rotate client secrets
  6. Request minimal scopes - Only request scopes you actually need
  7. Handle token expiration - Implement proper error handling for 401 responses

​
Common Errors

​
Invalid Client Credentials

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}
Verify your client_id and client_secret are correct.

​
Invalid Authorization Code

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid."
}
Authorization codes can only be used once and expire after 10 minutes.

​
Insufficient Scope

{
  "success": false,
  "message": "The access token is not authorized to perform this action."
}
Request the necessary scope when authorizing the application.

​
Next Steps

API Overview

Learn about available endpoints and API structure

Products API

Start managing your products via the API

Sales API

Retrieve and manage sales data

Webhooks

Set up real-time notifications for events

Build docs developers (and LLMs) love

Get started for freeTalk to us