Token-Based Authentication in Frappe Framework v15

Token-based authentication in Frappe Framework v15 enables secure, stateless REST API access using API keys and secrets instead of user passwords.

This guide explains how to generate, configure, and use tokens for ERPNext and Frappe applications while maintaining enterprise-grade security standards.

What Is Token-Based Authentication in Frappe?

Token-based authentication in Frappe uses API keys and API secrets to authenticate REST API requests without exposing user credentials.
Each token uniquely identifies a system user and allows controlled programmatic access to DocTypes and endpoints.

It is the preferred authentication method for:

• Mobile apps
• Third-party integrations
• Middleware services
• Automation tools

Why Use Token Authentication in ERPNext & Frappe?

Token authentication is recommended because it:

• Eliminates password sharing
• Supports stateless API calls
• Improves security isolation
• Enables granular user permissions

Works seamlessly with REST APIs

It is widely used in ERPNext integrations, BI dashboards, IoT connectors, and payment gateways.

Target Audience

• ERPNext API Developers
• Frappe Backend Engineers
• Integration Architects
• DevOps & Automation Teams
• SaaS Platform Builders

Technical Prerequisites

Before using token authentication, ensure:

How Does Token Authentication Work in Frappe v15?

Frappe generates a pair of credentials: API Key and API Secret for each user.

Authentication flow:

• System generates API credentials
• Client stores token securely
• Token is sent in HTTP headers
• Frappe validates token
• Request is authorized

No session cookies are used, making it ideal for headless systems.

How to Generate API Key and Secret in Frappe v15

Step 1: Open User Profile

Navigate to:

Desk → Users → Select User

Step 2: Generate API Credentials

Scroll to API Access section and click:

Generate Keys

This creates:

• api_key
• api_secret

Stored securely in the User DocType.

Step 3: Copy and Store Credentials

The API secret is displayed only once. Store it securely.

How to Use Token Authentication in REST API Calls

Authentication Header Format

Frappe v15 uses the following standard:

Authorization: token <api_key>:<api_secret>

Example: Fetch Data via REST API

curl -X GET https://your-site/api/resource/Customer \
-H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json"

Example: Create a New Document

curl -X POST https://your-site/api/resource/Lead \
-H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"lead_name": "ABC Corp",
"status": "Open"
}'

Supported API Endpoints with Token Auth

Token authentication works with:

Best Practices for Token Security

Follow these security guidelines:

• Use separate users for integrations
• Restrict permissions tightly
• Rotate tokens quarterly
• Never hardcode secrets
• Use environment variables
• Enable IP whitelisting
• Monitor API logs

Common Issues & Troubleshooting

Invalid Authorization Header

Cause: Incorrect token format
Fix: Ensure:

Authorization: token key:secret

Permission Denied Errors

Cause: User lacks DocType permissions
Fix: Assign proper roles

401 Unauthorized

Cause: Revoked or expired token
Fix: Regenerate credentials

Token Authentication vs OAuth in Frappe

Use token authentication for backend services and OAuth for public user apps.

Integration Patterns

Common Use Cases

• Mobile ERP apps
• Power BI integrations
• WhatsApp API connectors
• Payment gateway callbacks
• IoT manufacturing sensors

Enterprise Pattern

External System → Token Auth → Frappe API → ERPNext

This pattern ensures isolation and auditability.

Advanced: Programmatic Token Generation

Using Server-Side Script (Administrator Only)

import frappe
user = frappe.get_doc("User", "api.user@example.com")
api_key = frappe.generate_hash(length=15)
api_secret = frappe.generate_hash(length=15)
user.api_key = api_key
user.api_secret = api_secret
user.save()

Use only in controlled environments.

Technical Categories & Tags

• Frappe Framework v15
• REST API Security
• ERPNext Integration
• Token Authentication
• Backend Automation

Summary

Token-based authentication in Frappe Framework v15 provides a secure, lightweight, and scalable mechanism for REST API integrations.
By using API keys and secrets, developers can safely connect external systems to ERPNext without compromising user credentials.