Skip to main content

Introduction: What Is Token-Based Authentication in Frappe?

Token-based authentication in Frappe REST API allows external applications to securely access ERPNext services using API credentials instead of session cookies.

This method uses an API Key and API Secret to generate an access token, which is sent in every request header. It is ideal for system integrations, mobile backends, and automated services.
In Frappe v15, token authentication provides stateless, secure, and scalable API access.

What Is Token-Based Authentication in Frappe?

Answer

Token-based authentication is a security mechanism where API requests are authorized using a generated token derived from a user’s API key and secret.

It removes the need for session-based login and enables server-to-server communication.

Key Characteristics

  • Stateless authentication
  • Uses API key and secret
  • Sent via Authorization header
  • No cookie dependency
  • Suitable for automation

When Should You Use Token-Based Authentication?

Token-based authentication is recommended when:

  • Integrating third-party platforms
  • Building mobile or web apps
  • Creating automation workflows
  • Syncing multiple ERP systems
  • Running background jobs

It is best suited for backend and service-based integrations.

How to Generate API Key and Secret in

Frappe v15

Step 1: Open User Settings

Go to:

Desk → Users → Select User

Step 2: Locate API Access Section

Scroll to the API Access section in the user form.

Step 3: Generate API Credentials

Click:

Generate Keys

This creates:

API Key
API Secret

Step 4: Store Credentials Securely

Copy and save the credentials securely.
The API secret is displayed only once.

Best Practice

Create dedicated API users for integrations.

Example:

api.integration@company.com

How Token-Based Authentication Works

Answer

Frappe token authentication works by sending an API token in the request header using the format:

Authorization: token api_key:api_secret

This token is verified by the server before processing the request.

Authentication Header Format

Authorization: token <api_key>:<api_secret>

Example

Authorization: token 8c8c1ab12345:9fdde67890

How to Call Frappe REST API Using Token Authentication

Example 1: GET Request (Fetch Records)

curl -X GET https://example.com/api/resource/Customer \
-H "Authorization: token APIKEY:APISECRET"

Response

{
"data": [
{
"name": "ABC Pharma",
"customer_type": "Company"
}
]
}

Example 2: POST Request (Create Record)

curl -X POST https://example.com/api/resource/Lead \
-H "Authorization: token APIKEY:APISECRET" \
-H "Content-Type: application/json" \
-d '{
"lead_name": "David Smith",
"email_id": "david@test.com"
}'

Response

{
"data": {
"name": "LEAD-00015"
}
}

Example 3: PUT Request (Update Record)

curl -X PUT https://example.com/api/resource/Lead/LEAD-00015 \
-H "Authorization: token APIKEY:APISECRET" \
-H "Content-Type: application/json" \
-d '{"status":"Open"}'

Example 4: DELETE Request

curl -X DELETE https://example.com/api/resource/Lead/LEAD-00015 \
-H "Authorization: token APIKEY:APISECRET"

User Guidance: How Permissions Affect Token Access

Answer

Token-based API access follows the same permission rules as the associated user account.
If the user lacks permission, API requests will fail.

Required Permissions

Configure via:

Role Permission Manager

Ensure access to:

  • Read
  • Write
  • Create
  • Delete
  • Submit (if applicable)

Common Error

{
"exc_type": "PermissionError",
"message": "Not permitted"
}

Solution: Assign proper roles.

Best Practices for Token-Based Authentication

1. Use HTTPS Always

Never transmit API tokens over unsecured connections.

Always enable SSL/TLS.

2. Limit User Privileges

Assign minimum required permissions.
Avoid using Administrator credentials.

3. Rotate API Tokens Regularly

Regenerate API keys periodically.
Deactivate unused users.

4. Secure Token Storage

Store tokens in:

  • Environment variables
  • Secret managers
  • CI/CD pipelines
  • Avoid hardcoding.

5. Monitor API Activity

Use system logs to track:

  • Failed attempts
  • High usage
  • Unauthorized access

Integration Patterns Using Token Authentication

Pattern 1: ERPNext + CRM Sync

Synchronize leads, contacts, and deals securely.

Pattern 2: Mobile App Backend

Backend server authenticates with ERPNext using tokens.
Avoid client-side exposure.

Pattern 3: Accounting Integration

Connect billing systems and payment gateways.

Pattern 4: Manufacturing Systems

Push production and inventory data.

Advanced Topic: Using Token Authentication in Python

Example

import requests
url = "https://example.com/api/resource/Item"
headers = {
"Authorization": "token APIKEY:APISECRET"
}
response = requests.get(url, headers=headers)
print(response.json())

Advantages

  • Simple implementation
  • No session handling
  • Ideal for microservices
  • Scalable

Troubleshooting Common Token Authentication Issues

Issue 1: 401 Unauthorized

Cause

  • Invalid token
  • Typo in credentials
  • Revoked key

Solution

Regenerate credentials.

Issue 2: 403 Forbidden

Cause

Permission restrictions.

Solution

Update user roles.

Issue 3: Token Not Working After Reset

Cause

Cached credentials.

Solution

Restart integration services.

Issue 4: Incorrect Header Format

Cause

Missing “token” keyword.

Solution

Use:

Authorization: token key:secret

Comparison: Token Authentication vs Simple Authentication

Feature Token Auth Simple Auth
Format token key:secret Basic base64
Security High Medium
Setup Easy Easy
Best Use Production APIs Internal APIs
Scalability High Moderate

Frequently Asked Questions (FAQs)

1. Is token-based authentication secure in Frappe v15?

Yes. When used with HTTPS and restricted permissions, token authentication is secure for enterprise integrations.

2. Can one user have multiple API tokens?

No. Each user has one active API key and secret at a time.

3. Can I revoke API access?

Yes. Regenerate keys or disable the user account.

4. Is OAuth better than token authentication?

OAuth is better for public APIs. Token authentication is ideal for private integrations.

5. Can I use token authentication in production?

Yes, provided security best practices are followed.

Industry Relevance

Token-based authentication is widely used in:

  • Manufacturing ERP systems
  • Healthcare platforms
  • Fintech solutions
  • Logistics networks
  • SaaS applications

It enables secure digital ecosystems.

Cross References

Related topics:

  • Simple Authentication in Frappe
  • OAuth2 Authentication
  • Webhooks Integration
  • REST API Overview

Conclusion: Secure API Integration with Frappe Token Authentication

Token-based authentication in Frappe REST API v15 offers a secure, scalable, and developer-friendly method for integrating external systems with ERPNext.

By using API keys and secrets, organizations can:

  • Enable secure automation
  • Reduce security risks
  • Simplify integrations
  • Improve data consistency
  • Scale digital operations

When implemented correctly, token authentication becomes the backbone of modern ERPNext integrations.

References

Official Docs:

https://docs.frappe.io/framework/user/en/guides/integration/rest_api/token_based_authentication

Frappe GitHub v15:

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

Rating: 0 / 5 (0 votes)

© 2026 | goERPNext | All rights reserved