Skip to main content

Introduction & Context

Frappe Framework v15 provides a built-in OAuth 2.0 implementation that allows external applications to authenticate users and access protected resources securely. By using Frappe as an OAuth service, developers can enable standardized, token-based authentication for APIs, portals, and third-party applications.

This mechanism is widely used for:

  • Securing REST API endpoints
  • Integrating mobile or web applications
  • Enabling Single Sign-On (SSO)
  • Managing access tokens centrally

Frappe’s OAuth implementation follows OAuth 2.0 standards and is tightly integrated with the User and Authorization system.

What Is Frappe OAuth Service?

Frappe OAuth Service is an authentication system that allows third-party applications to obtain secure access tokens from Frappe and use them to access protected APIs.

It enables:

  • Token-based authentication
  • Controlled API access
  • Role-based permissions
  • Secure external integrations

OAuth replaces traditional username-password authentication for API usage.

Technical Prerequisites

Before implementing OAuth in Frappe v15, ensure:

  • Frappe Framework v15 is installed
  • Site is configured and active
  • REST API access is enabled
  • User roles and permissions are defined
  • HTTPS is enabled in production

Recommended environment:

  • Python 3.10+
  • MariaDB 10.6+
  • Node.js 18+

How Does OAuth Work in Frappe v15?

Frappe follows the standard OAuth 2.0 Authorization Code and Password Grant flows.

Basic Flow

  1. Client registers with Frappe
  2. Client requests authorization
  3. User approves access
  4. Frappe issues access token
  5. Client uses token for API calls

All tokens are stored and validated within the Frappe database.

Supported OAuth Grant Types in Frappe

Frappe v15 supports:

Grant Type Purpose
Authorization Code Web and portal apps
Password Grant Trusted internal apps
Refresh Token Token renewal
Client Credentials Service integrations

Configuration & Setup

Step 1: Create an OAuth Client

To enable OAuth, create an OAuth Client in Frappe.

  1. Login as Administrator
  2. Go to: OAuth Client
  3. Click New
  4. Fill the following fields:
Field Description
App Name Name of your application
Redirect URIs Callback URL
Client Type Confidential / Public
Default Scopes API access level

5. Save the document

After saving, Frappe generates:

  • Client ID
  • Client Secret

These credentials are required for authentication.

Step 2: Configure Redirect URI

Redirect URI must match exactly with the one used by the client.

Example:

https://example.com/oauth/callback

Mismatch will cause authorization failure.

Step 3: Enable Required Scopes

Scopes define access levels.

Common scopes:

  • all – Full API access
  • read – Read-only access
  • write – Data modification

Scopes are defined in the OAuth Client document.

Implementation Details

OAuth Authorization Endpoint

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

Used to initiate user authorization.

Token Endpoint

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

Used to obtain access tokens.

Token Validation

Frappe validates tokens internally using:

  • OAuth Token DocType
  • User permissions
  • Expiry time

Expired tokens are rejected automatically.

Code Examples & API Usage

1. Authorization Request

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

This redirects the user to login and approve access.

2. Token Exchange (Authorization Code)

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

Request Body:

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

Response:

{
"access_token": "token_value",
"refresh_token": "refresh_value",
"expires_in": 3600
}

3. Password Grant Example

{
"grant_type": "password",
"username": "user@example.com",
"password": "password",
"client_id": "CLIENT_ID",
"client_secret": "CLIENT_SECRET"
}

Used only for trusted applications.

4. Using Access Token

GET /api/resource/Sales Order

Authorization: Bearer ACCESS_TOKEN
This allows secure API access.

User Guidance: Managing OAuth Access

Viewing OAuth Tokens

Go to:

OAuth Token List

Here you can:

  • Monitor active tokens
  • Check expiry
  • Revoke access

Revoking Tokens

To disable access:

  1. Open OAuth Token
  2. Click Delete / Disable

Access is immediately revoked.

Restricting Access with Roles

OAuth tokens follow user permissions.

Ensure:

  • Proper role assignment
  • Limited API access
  • Principle of least privilege

Best Practices & Tips

Security Best Practices

  • Use HTTPS only
  • Store client secrets securely
  • Avoid exposing tokens
  • Rotate secrets periodically
  • Disable unused clients

Performance Optimization

  • Use refresh tokens
  • Avoid frequent re-authentication
  • Cache tokens securely
  • Monitor token expiry

Compliance Recommendations

  • Maintain audit logs
  • Restrict admin access
  • Review OAuth clients quarterly
  • Enable IP whitelisting if required

Advanced Topics

Custom OAuth Scopes

You can define custom scopes by extending:

frappe.oauth

Scopes can be mapped to specific API endpoints.

Integration with Mobile Applications

Frappe OAuth is suitable for:

  • Android apps
  • iOS apps
  • React / Flutter apps

Use Authorization Code + PKCE for mobile security.

OAuth with External Identity Providers

Frappe can act as:

  • OAuth Provider
  • OAuth Consumer

This allows SSO integration with Google, Azure, etc.

Integration Patterns

Common Integration Scenarios

Use Case Pattern
Mobile App OAuth + Token Auth
BI Tool Client Credentials
Partner Portal Authorization Code
IoT Device Service Token

ERPNext API Integration

ERPNext APIs automatically support OAuth through Frappe’s framework layer.
No additional configuration is required.

Real-World Example

Scenario: Mobile Sales App Integration

A sales team uses a mobile app connected to ERPNext.

Workflow:

  1. App redirects to Frappe login
  2. User authorizes app
  3. Token generated
  4. App fetches Orders, Customers
  5. Token refreshed periodically

Result:

  • Secure access
  • No password sharing
  • Centralized control

Troubleshooting Common Issues

Invalid Client Error

Cause:
Wrong Client ID or Secret

Solution:
Verify credentials in OAuth Client.

Redirect URI Mismatch

Cause:
Callback URL mismatch

Solution:
Update Redirect URI to exact value.

Token Expired

Cause:
Access token timeout

Solution:
Use refresh token to regenerate.

Permission Denied

Cause:
User role restriction

Solution:
Update Role Permissions.

Cross-References

For related topics, see:

  • REST API Authentication
  • Portal Development
  • Web Forms Security
  • Role-Based Permissions
  • API Rate Limiting

Industry Relevance

Frappe OAuth is widely used in:

  • ERP systems
  • SaaS platforms
  • Mobile applications
  • Partner portals
  • B2B integrations

It enables secure digital ecosystems.

Target Audience Tags

  • ERP Developers
  • Frappe Consultants
  • API Engineers
  • System Integrators
  • SaaS Architects

Conclusion

Using Frappe as an OAuth service in Framework v15 enables secure, scalable, and standardized authentication for modern applications. It eliminates password-based API access, improves security compliance, and simplifies third-party integrations.
By configuring OAuth clients, managing scopes, and following best practices, organizations can build reliable API ecosystems on top of ERPNext and Frappe.
For production environments, OAuth should be the default authentication mechanism for all external integrations.

Rating: 0 / 5 (0 votes)

© 2026 | goERPNext | All rights reserved