How do you enable token-based authentication in Frappe v15?

You generate an API Key and API Secret for a user and pass them in HTTP headers to authenticate REST API requests.
In Frappe Framework, token-based authentication is the simplest and most reliable method for securing API access without interactive login sessions.
It is widely used in ERPNext integrations, automation scripts, and middleware platforms.

What Is Token-Based Authentication in Frappe?

Token-based authentication in Frappe uses:

• API Key
• API Secret

These credentials are generated per user and used to authenticate API calls via HTTP headers.

Unlike session-based login, token authentication is:

• Stateless
• Automation-friendly
• Suitable for backend integrations
• Secure when used with HTTPS

Why Use Token Authentication in Frappe?

Token-based authentication is recommended for:

• External system integration
• Data synchronization
• ETL pipelines
• Mobile backends
• Scheduled automation
• BI and reporting tools

It avoids browser sessions and enables long-running API access securely.

Technical Prerequisites

Before configuring token authentication, ensure:

• Frappe Framework v15 is installed
• REST API is enabled
• User account exists
• HTTPS is active in production
• Administrator/System Manager access

Authentication Architecture in Frappe v15

Token authentication works using:

Authentication Model: Header-Based API Token

Step-by-Step: How to Set Up Token-Based Authentication

Step 1: Generate API Key and API Secret

1. Log in as Administrator
2. Open User List
3. Select the target user
4. Scroll to API Access
5. Click Generate Keys

You will receive:

• API Key
• API Secret (shown once)

Save the secret securely. It cannot be retrieved again.

Step 2: Enable API Access (If Required)

Ensure the user has:

• Required roles
• API permission
• Read/Write access to DocTypes

Recommended roles:

System Manager / API User / Custom Integration Role

Step 3: Authenticate Using HTTP Headers

Use the following header format:

Authorization: token API_KEY:API_SECRET

Example

Authorization: token 123abc:456xyz

Step 4: Call Frappe REST API

Example: Fetch Customers

curl -X GET https://yoursite.com/api/resource/Customer \
-H "Authorization: token 123abc:456xyz"

Sample Response

{
"data": [
{
"name": "CUST-0001",
"customer_name": "ABC Pvt Ltd"
}
]
}

Step 5: Create Records Using Token Auth

Example: Insert Data

curl -X POST https://yoursite.com/api/resource/Lead \
-H "Authorization: token 123abc:456xyz" \
-H "Content-Type: application/json" \
-d '{
"lead_name": "New Lead",
"email_id": "lead@example.com"
}'

Token Storage in Frappe

Frappe stores API credentials in:

User → api_key
User → api_secret

Internally, secrets are encrypted and validated during request processing.

Real-World Integration Example

Automated Data Sync System

Scenario: Sync orders from external CRM

Flow:

1. Generate API credentials
2. Store in integration service
3. Authenticate every request
4. Push/pull data periodically
5. Monitor logs

Used in:

• CRM ↔ ERP integrations
• E-commerce connectors
• Warehouse systems
• Logistics middleware

Best Practices & Security Guidelines

Follow these recommendations:

• Always use HTTPS
• Rotate API keys periodically
• Limit user permissions
• Store secrets securely
• Revoke unused credentials
• Monitor API usage

Recommended practice:

Generate one API user per integration

Avoid sharing credentials across systems.

Advanced Configuration Options

1. Programmatic Key Generation

Using server-side scripting:

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

Use only in secure backend contexts.

2. Token Revocation

To revoke access:

• Open User
• Regenerate keys
• Save

Old tokens become invalid instantly.

3. IP Restriction (Custom Implementation)

For enhanced security, you can:

• Implement IP filtering
• Add middleware validation
• Use reverse proxy rules

This requires custom app logic.

Integration Patterns

Troubleshooting Common Issues

Invalid Authorization Header

Cause: Wrong format
Fix:
Authorization: token key:secret

Authentication Failed

Cause:

• Wrong credentials
• Revoked token

Fix:

• Regenerate keys
• Update integration

Permission Denied

Cause:

• Missing role permission

Fix:

• Assign proper roles
• Check DocType permissions

401 Unauthorized

Cause:

• Expired/replaced token

Fix:

• Generate new API credentials

Cross-References

Recommended internal links for goerpnext.com:

• OAuth Authentication in Frappe
• REST API Integration Guide
• API Rate Limiting
• User Permission Management
• Secure ERPNext Integrations

Technical Categories

• Frappe Modules: Integration, Database, Desk
• Technical Terms: API Key, API Secret, REST API, Token Auth
• Targeted Tags: ERPNext Customization, Frappe Framework Tutorial

Target Audience Tags

• ERPNext Developers
• Integration Engineers
• API Developers
• DevOps Engineers
• System Administrators

Industry Relevance

Token-based authentication is used in:

• Manufacturing ERP systems
• Chemical ERP platforms
• Supply chain automation
• SaaS integrations
• Financial systems

It supports compliance-ready and scalable API security.

Summary

Frappe Framework v15 provides built-in token-based authentication using API keys and secrets. This method is ideal for backend integrations, automation, and third-party systems that require secure and reliable REST API access without interactive login sessions.
When implemented with proper role control and HTTPS, token authentication forms the foundation of enterprise-grade ERPNext integrations.