Skip to main content

Introduction: What Is Simple Authentication in Frappe REST API?

Simple Authentication in Frappe REST API is a token-based security mechanism that allows external applications to access ERPNext or Frappe services using an API key and API secret.

It provides a lightweight and secure way to authenticate REST requests without session cookies or OAuth workflows. This method is ideal for system integrations, automation scripts, and third-party applications.
In Frappe v15, simple authentication is implemented using Authorization headers with encoded API credentials.

What Is Simple Authentication in Frappe?

Answer:

Simple Authentication is an API security method where a client sends an API key and secret in the request header to authenticate with a Frappe site.

It allows stateless authentication for REST APIs without creating login sessions.

Key Characteristics

  • Token-based authentication
  • No session management
  • Suitable for server-to-server communication
  • Works over HTTPS
  • Lightweight and fast

When Should You Use Simple Authentication?

Simple Authentication is recommended when:

  • Integrating external systems
  • Building mobile applications
  • Creating automation scripts
  • Developing microservices
  • Running background integrations

It is not recommended for browser-based interactive applications where session authentication is more suitable.

How to Generate API Key and Secret in Frappe v15

Step 1: Open User List

Navigate to:

Desk → Users → User List

Step 2: Select User

Open the user account that will access the API.
Prefer using a dedicated “API User” for security.

Step 3: Generate API Credentials

Scroll to the API Access section and click:

Generate Keys

This creates:

  • API Key
  • API Secret

Step 4: Save Securely

Copy and store the credentials securely.

The API secret is shown only once.

Best Practice

Create a separate user for each integration.

Example:

api.integration@company.com

How to Authenticate REST API Requests in Frappe

Answer:

Authentication is done by sending the API key and secret in the Authorization header using Basic Authentication format.

Authentication Format

Authorization: Basic base64(api_key:api_secret)

Example Structure

Authorization: Basic ZXJwQGdtYWlsLmNvbTphYmNkMTIzNA==

Where:

ZXJwQGdtYWlsLmNvbTphYmNkMTIzNA== = base64(api_key:api_secret)

Step-by-Step: Creating Authorization Header

Step 1: Combine Credentials

api_key:api_secret

Example:

1234567890:abcdef12345

Step 2: Encode in Base64

Using terminal:

echo -n "1234567890:abcdef12345" | base64

Output:

MTIzNDU2Nzg5MDphYmNkZWYxMjM0NQ==

Step 3: Add to Header

Authorization: Basic MTIzNDU2Nzg5MDphYmNkZWYxMjM0NQ==

How to Call Frappe REST API Using Simple Authentication

Example 1: GET Request (Fetch Data)

Request

curl -X GET https://example.com/api/resource/Customer \
-H "Authorization: Basic BASE64_ENCODED_TOKEN"

Response

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

Example 2: POST Request (Create Record)

Request

curl -X POST https://example.com/api/resource/Lead \
-H "Authorization: Basic BASE64_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"lead_name": "John Smith",
"email_id": "john@test.com"
}'

Response

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

Example 3: PUT Request (Update Record)

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

Example 4: DELETE Request

curl -X DELETE https://example.com/api/resource/Lead/LEAD-00012 \
-H "Authorization: Basic BASE64_TOKEN"

User Guidance: How Permissions Affect API Access

Answer:

API access follows the same permission rules as the logged-in user.

If the user does not have permission, API calls will fail.

Required Permissions

Ensure the API user has:

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

Configured via:

Role Permission Manager

Common Permission Error

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

Solution: Assign proper roles.

Security Best Practices for Simple Authentication

1. Always Use HTTPS

Never send API credentials over HTTP.
Use TLS encryption.

2. Restrict API User Roles

Assign minimum required permissions.
Follow principle of least privilege.

3. Rotate API Keys Periodically

Regenerate keys every 6–12 months.
Revoke unused credentials.

4. Use Environment Variables

Never hardcode secrets.

Store in:

  • .env files
  • Vault services
  • CI/CD secrets

5. Monitor API Logs

Track unusual activity.

Use:

Error Log
Activity Log

Integration Patterns Using Simple Authentication

Pattern 1: ERPNext + CRM Integration

Use API authentication to sync:

  • Leads
  • Contacts
  • Opportunities

Pattern 2: Mobile App Backend

Mobile server authenticates with ERPNext via API.
Avoid direct client-side credentials.

Pattern 3: Accounting System Sync

Exchange:

  • Invoices
  • Payments
  • Ledgers

Pattern 4: IoT and Manufacturing Data

Push production data to ERPNext.

Advanced Topic: Using API Tokens with Server Scripts

Answer:

Server scripts can authenticate internally using session context, but external calls still require API tokens.

Example in Python:

import requests
import base64
token = base64.b64encode(b"key:secret").decode()
headers = {
"Authorization": f"Basic {token}"
}
response = requests.get(
"https://example.com/api/resource/Item",
headers=headers
)
print(response.json())

Troubleshooting Common Authentication Issues

Issue 1: 401 Unauthorized

Cause

  • Invalid token
  • Wrong encoding
  • Revoked keys

Solution

Re-generate API credentials.

Issue 2: 403 Forbidden

Cause

Insufficient permissions.

Solution

Update role permissions.

Issue 3: Token Not Working After Regeneration

Cause

Old token cached.

Solution
Clear cache and update integrations.

Issue 4: Base64 Encoding Errors

Cause

Extra spaces or newline characters.

Solution

Use -n flag in echo.

Comparison: Simple Auth vs OAuth2

Feature Simple Auth OAuth2
Setup Easy Complex
Security Medium High
Tokens Static Rotating
Use Case Internal APIs Public APIs
Performance Fast Moderate

Conclusion: Secure and Scalable API Access with Frappe v15

Simple Authentication in Frappe REST API provides a fast, reliable, and developer-friendly method for integrating external systems with ERPNext.

By using API keys and secrets, organizations can:

  • Enable secure automation
  • Simplify integrations
  • Reduce development time
  • Improve data consistency
  • Scale digital operations

When implemented with strong security practices, simple authentication becomes a foundational component of modern ERPNext integrations.

References

Official Docs: https://docs.frappe.io/framework/user/en/guides/integration/rest_api/simple_authentication
GitHub v15: https://github.com/frappe/frappe/tree/version-15

Rating: 0 / 5 (0 votes)

© 2026 | goERPNext | All rights reserved