Skip to main content

Introduction: What Is OAuth 2 in Frappe Framework?

OAuth 2 in Frappe Framework provides a secure, standards-based authentication mechanism that allows third-party applications to access ERPNext resources without sharing user credentials.
Unlike simple or token authentication, OAuth 2 introduces access tokens, authorization flows, and scoped permissions, making it ideal for public APIs, SaaS integrations, and multi-tenant applications.
Frappe v15 acts as an OAuth 2 Provider, issuing tokens that external applications use to access protected REST API endpoints.

What Is OAuth 2 Authentication in Frappe?

Answer

OAuth 2 authentication in Frappe is a token-based authorization framework where users grant limited access to their data through access tokens issued by Frappe.
It enables secure, revocable, and scoped API access without exposing user passwords.

Key Features of OAuth 2 in Frappe v15

  • Standards-compliant OAuth 2 implementation
  • Access token–based authorization
  • User consent-driven access
  • Token expiration and revocation
  • Suitable for public and third-party apps

When Should You Use OAuth 2 in Frappe?

OAuth 2 is recommended when:

  • Building public APIs
  • Creating SaaS platforms on ERPNext
  • Allowing third-party app integrations
  • Exposing APIs to external developers
  • Implementing fine-grained access control

For internal system-to-system integrations, token authentication may be simpler. For external apps, OAuth 2 is the preferred approach.
OAuth 2 Architecture in Frappe (v15)

Answer

Frappe implements OAuth 2 using a provider model with registered clients, authorization codes, and access tokens.

Core OAuth 2 Components

Component Description
OAuth Client External application requesting access
Resource Owner ERPNext user
Authorization Server Frappe Framework
Access Token Token used to access APIs
Scopes Permission boundaries

How to Enable OAuth 2 in Frappe v15

OAuth 2 is enabled by default in Frappe v15. Configuration is done through the

DeskStep

1: Open OAuth Client List

Navigate to:

Desk → OAuth Client

Step 2: Create a New OAuth Client

Click New and configure the following:

Required Fields

  • App Name – Name of the external application
  • Redirect URIs – Allowed callback URLs
  • Default Scopes – Permissions (e.g., read, write)
  • Grant Type – Authorization Code

Step 3: Save Client Credentials

After saving, Frappe generates:

  • Client ID
  • Client Secret

Store the client secret securely.

OAuth 2 Authorization Flow in Frappe

Answer

Frappe supports the Authorization Code Grant, the most secure OAuth 2 flow.

Step-by-Step Authorization Code Flow

Step 1: Redirect User for Authorization

GET /api/method/frappe.integrations.oauth2.authorize?
response_type=code
&client_id=CLIENT_ID
&redirect_uri=REDIRECT_URI
&scope=read write
&state=xyz

User logs in and grants consent.

Step 2: Receive Authorization Code

Frappe redirects to:

REDIRECT_URI?code=AUTH_CODE&state=xyz

Step 3: Exchange Code for Access Token

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

Payload

{
"grant_type": "authorization_code",
"code": "AUTH_CODE",
"client_id": "CLIENT_ID",
"client_secret": "CLIENT_SECRET",
"redirect_uri": "REDIRECT_URI"
}

Step 4: Receive Access Token

{
"access_token": "ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}

How to Call Frappe REST API Using OAuth 2

Answer

OAuth-protected APIs are accessed using a Bearer token in the Authorization header.

Authorization Header Format

Authorization: Bearer ACCESS_TOKEN

Example: GET API Call

curl -X GET https://example.com/api/resource/Item \
-H "Authorization: Bearer ACCESS_TOKEN"

Example: POST API Call

curl -X POST https://example.com/api/resource/Lead \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"lead_name": "OAuth Lead",
"email_id": "oauth@test.com"
}'

User Guidance: OAuth Scopes and Permissions

Answer

Scopes define what actions an OAuth client can perform.

Common Scope Examples

  • read – View data
  • write – Create or update data
  • delete – Remove records

Scopes are enforced at runtime based on user permissions.

Token Expiration and Revocation

Answer

OAuth tokens in Frappe are time-bound and can be revoked.

Token Expiry

  • Default expiry: 1 hour
  • Automatically invalidated after expiry

Token Revocation

Tokens can be revoked by:

  • Disabling the OAuth client
  • Revoking user access
  • Rotating client secrets

Best Practices for OAuth 2 in Frappe

1. Always Use HTTPS

OAuth tokens must never be transmitted over HTTP.

2. Use Authorization Code Flow Only

Avoid insecure flows for production use.

3. Restrict Scopes

Grant minimum required access.

4. Secure Client Secrets

Store secrets in environment variables or secret managers.

5. Monitor Token Usage

Audit API access logs regularly.

Troubleshooting Common OAuth 2 Issues

Issue 1: Invalid Client Error

Cause: Wrong client ID or secret
Solution: Verify OAuth client configuration

Issue 2: Redirect URI Mismatch

Cause: Callback URL not whitelisted
Solution: Add exact redirect URI in OAuth Client

Issue 3: Token Expired

Cause: Token lifetime exceeded
Solution: Request a new access token

Issue 4: 401 Unauthorized

Cause: Missing or invalid Bearer token
Solution: Include valid Authorization header

OAuth 2 vs Token Authentication in Frappe

Feature OAuth 2 Token Auth
Security Very High High
User Consent Yes No
Token Expiry Yes No
Public APIs Ideal Not Recommended
Setup Complexity Moderate Simple

Frequently Asked Questions (FAQs)

1. Is OAuth 2 secure in Frappe v15?

Yes. Frappe’s OAuth 2 implementation follows standard security practices and is suitable for enterprise-grade integrations.

2. Can OAuth 2 be used in production ERPNext systems?

Yes. OAuth 2 is recommended for public and third-party integrations.

3. Does OAuth replace token authentication?

No. OAuth complements token authentication. Each serves different use cases.

4. Can I limit API access per app?

Yes. OAuth scopes and permissions enforce granular access control.

5. Can tokens be revoked manually?

Yes. Tokens can be revoked by disabling clients or users.

Industry Relevance

OAuth 2 in Frappe is widely used in:

  • SaaS ERP platforms
  • Fintech integrations
  • Healthcare systems
  • Manufacturing portals
  • Multi-tenant applications

It enables secure, scalable digital ecosystems.

Cross References

Related documentation:

  • Token-Based Authentication in Frappe
  • Simple Authentication
  • REST API Overview
  • Webhooks in Frappe

Conclusion: Secure API Access with OAuth 2 in Frappe v15

OAuth 2 authentication in Frappe REST API v15 provides a robust, secure, and scalable solution for modern integrations.

By implementing OAuth 2, organizations can:

  • Protect user credentials
  • Enable third-party ecosystems
  • Control access with scopes
  • Scale API usage securely
  • Build future-ready ERP solutions

For public APIs and external integrations, OAuth 2 is the recommended authentication standard in Frappe.

References

Official Documentation:

https://docs.frappe.io/framework/user/en/guides/integration/rest_api/oauth-2

Frappe GitHub v15:

https://github.com/frappe/frappe/tree/version-15

Rating: 0 / 5 (0 votes)

© 2026 | goERPNext | All rights reserved