Introduction & Context

How do you set up OAuth in Frappe Framework v15?

You configure OAuth by creating an OAuth Client, defining redirect URIs, and enabling token-based authentication using Frappe’s built-in OAuth2 provider.

In Frappe Framework, OAuth enables secure third-party access to APIs and allows external systems to authenticate users without exposing passwords.

This feature is widely used in ERPNext integrations, mobile apps, and external portals.

What Is OAuth in Frappe?

OAuth in Frappe is an implementation of OAuth 2.0 Authorization Code Flow that allows:

•  Secure API authentication
• Token-based access
• Third-party application integration
• External system login

It is powered by Frappe’s built-in OAuth Client and OAuth Authorization Server modules.

Why Use OAuth Integration in Frappe?

OAuth integration is recommended when you need:

• Mobile app authentication
• External CRM/BI integration
• API-based automation
• Secure SSO-style login
• Partner application access

OAuth eliminates the need for sharing usernames and passwords with external systems.

Technical Prerequisites

Before configuring OAuth, ensure:

• Frappe Framework v15 is installed
• Developer Mode is enabled
• REST API access is active
• HTTPS is configured in production
• System Manager access is available

OAuth Architecture in Frappe v15

Frappe OAuth works using three main components:

Flow Type: Authorization Code Grant

Step-by-Step: How to Set Up OAuth in Frappe v15

Step 1: Create an OAuth Client

• Log in as Administrator
• Go to:

Settings → OAuth Client

• Click New

Fill in the following fields:

• Save the record

After saving, Frappe generates:

• Client ID
• Client Secret

Step 2: Configure Redirect URI

Redirect URI must match exactly:

Example:

https://myapp.com/oauth/callback

Important rules:

• Must use HTTPS (production)
• No trailing spaces
• Must match client config

Step 3: Generate Authorization Code

Use this endpoint:

/api/method/frappe.integrations.oauth2.authorize

Example URL

https://yoursite.com/api/method/frappe.integrations.oauth2.authorize?
client_id=CLIENT_ID
&response_type=code
&redirect_uri=REDIRECT_URI
&scope=all
&state=123

After login, Frappe redirects with:

?code=AUTHORIZATION_CODE

Step 4: Exchange Code for Access Token

Call the token endpoint:

/api/method/frappe.integrations.oauth2.get_token

Example Request

curl -X POST https://yoursite.com/api/method/frappe.integrations.oauth2.get_token \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "redirect_uri=REDIRECT_URI" \
-d "client_id=CLIENT_ID" \
-d "client_secret=CLIENT_SECRET"

Sample Response

{
"access_token": "abc123",
"refresh_token": "xyz456",
"expires_in": 3600,
"token_type": "Bearer"
}

Step 5: Access Protected APIs Using Token

Include token in headers:

Authorization: Bearer ACCESS_TOKEN

Example API Call

curl -H "Authorization: Bearer abc123" \
https://yoursite.com/api/resource/Customer

Token Management in Frappe

Frappe stores tokens in:

OAuth Bearer Token

Doctype

Token lifecycle:

You can regenerate access tokens using refresh tokens.

Refresh Token Flow

Request

POST /api/method/frappe.integrations.oauth2.get_token

With:

grant_type=refresh_token
refresh_token=REFRESH_TOKEN

Purpose

• Prevents re-login
• Improves session continuity
• Enables long-term integrations

Real-World Integration Example

Mobile App Authentication

Use OAuth to:

1. Redirect user to Frappe login
2. Get authorization code
3. Exchange for token
4. Access ERPNext APIs
5. Refresh tokens automatically

This is commonly used in:

• Field sales apps
• Inventory scanners
• HR self-service portals

Best Practices & Security Guidelines

• Always use HTTPS
• Store client secrets securely
• Rotate secrets periodically
• Limit scope access
• Monitor token usage
• Revoke unused clients

Recommended:

Settings → OAuth Client → Disable unused apps

Advanced Configuration Options

Custom Token Expiry

You can override token expiry in:

frappe.conf.oauth_token_expiry

Restricting API Scope

Scopes supported:

• all
• Custom permission-based scopes

Advanced scope customization requires app-level hooks.

Integration Patterns

Troubleshooting Common Issues

Invalid Client Error

Cause:

• Wrong client_id
• Disabled OAuth client

Fix:

• Verify OAuth Client record

Redirect URI Mismatch

Cause:

• URI mismatch
• Extra slash

Fix:

• Match exact URI in settings

Token Expired

Cause:

• Access token expired

Fix:

• Use refresh token

Permission Denied

Cause:

• User lacks role permission

Fix:

• Assign proper roles

Cross-References

Recommended internal links for goerpnext.com:

• Frappe REST API Authentication
• Social Login Integration
• Generic OAuth Client Setup
• API Rate Limiting
• Token Security in ERPNext

Technical Categories

• Frappe Modules: Integration, Database, Desk
• Technical Terms: OAuth2, Access Token, Refresh Token, REST API
• Targeted Tags: ERPNext Customization, Frappe Framework Tutorial

Target Audience Tags

• ERPNext Developers
• System Integrators
• Mobile App Developers
• API Engineers
• IT Administrators

Industry Relevance

OAuth in Frappe is widely used in:

• Manufacturing ERPs
• Chemical ERP Solutions
• Logistics Systems
• Fintech Integrations
• SaaS Platforms

It enables compliance-ready and scalable authentication models.

Summary

Frappe Framework v15 provides a built-in, secure OAuth2 implementation that enables modern authentication for APIs, mobile apps, and external integrations. By configuring OAuth Clients and using authorization code flow, developers can build scalable and compliant systems without managing passwords externally.
OAuth is the recommended authentication method for all production-grade ERPNext integrations.