ERPNext provides multiple authentication methods for API access. All API requests must be authenticated to ensure secure access to your data.
Authentication Methods
ERPNext supports three primary authentication methods:
- API Key and Secret - Recommended for server-to-server integrations
- Token-based Authentication - For session-based access
- OAuth 2.0 - For third-party application integrations
API Key and Secret (Recommended)
API keys provide secure, long-lived credentials for programmatic access to ERPNext.
Generating API Keys
Log in to ERPNext
Access your ERPNext instance with administrator privileges.
Navigate to User
Go to User List and select the user for whom you want to generate API credentials.
Generate Keys
Scroll down to the API Access section and click Generate Keys.
Save Credentials
Copy both the API Key and API Secret. The secret will only be shown once.
Store your API Secret securely. It will only be displayed once during generation. If lost, you’ll need to regenerate new credentials.
Using API Keys
Include the API key and secret in the Authorization header:
curl -X GET \
'https://your-instance.erpnext.com/api/resource/Customer' \
-H 'Authorization: token api_key:api_secret'
Python SDK Example
Use the frappe-client Python package for easier integration:
from frappe_client import FrappeClient
client = FrappeClient(
url="https://your-instance.erpnext.com",
api_key="your_api_key_here",
api_secret="your_api_secret_here"
)
# Get a document
customer = client.get_doc("Customer", "CUST-00001")
print(customer.customer_name)
# Get a list
customers = client.get_list(
"Customer",
fields=["name", "customer_name", "territory"],
filters=[["territory", "=", "United States"]],
limit_page_length=10
)
# Create a document
new_customer = client.insert({
"doctype": "Customer",
"customer_name": "John Doe",
"customer_type": "Individual",
"territory": "United States"
})
print(f"Created: {new_customer.name}")
# Update a document
customer = client.get_doc("Customer", "CUST-00001")
customer.mobile_no = "+1-555-0123"
client.update(customer)
# Delete a document
client.delete("Customer", "CUST-00001")
pip install frappe-client
Token-Based Authentication
Token-based authentication is useful for web applications where users log in with credentials.
Login to Get Token
curl -X POST \
'https://your-instance.erpnext.com/api/method/login' \
-H 'Content-Type: application/json' \
-d '{
"usr": "[email protected]",
"pwd": "password"
}'
When using token-based authentication with login, the session is maintained via cookies. Keep the session alive by making periodic requests or implement token refresh logic.
Logout
curl -X POST \
'https://your-instance.erpnext.com/api/method/logout' \
--cookie 'cookies_from_login'
Password-Based Authentication
For simple use cases, you can use Basic Authentication (not recommended for production):
curl -X GET \
'https://your-instance.erpnext.com/api/resource/Customer' \
-u 'username:password'
Basic Authentication sends credentials with every request. Always use HTTPS and prefer API keys for production environments.
OAuth 2.0
For third-party applications, ERPNext supports OAuth 2.0 authentication.
Setting Up OAuth
Create OAuth Client
Navigate to Social Login Key in ERPNext and create a new OAuth provider configuration.
Configure Redirect URI
Set the redirect URI where users will be sent after authorization.
Implement OAuth Flow
Use the authorization code flow to obtain access tokens.
OAuth Authorization Flow
- Authorization Request: Direct users to the authorization endpoint
https://your-instance.erpnext.com/api/method/frappe.integrations.oauth2.authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REDIRECT_URI
&scope=all
- Exchange Code for Token:
curl -X POST \
'https://your-instance.erpnext.com/api/method/frappe.integrations.oauth2.get_token' \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "authorization_code",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_REDIRECT_URI",
"client_id": "YOUR_CLIENT_ID"
}'
- Use Access Token:
curl -X GET \
'https://your-instance.erpnext.com/api/resource/Customer' \
-H 'Authorization: Bearer ACCESS_TOKEN'
Permissions and User Roles
API authentication is tied to ERPNext user permissions:
- API requests execute with the permissions of the authenticated user
- Users must have appropriate role permissions for DocTypes they access
- System Manager role has full access to all resources
- Custom roles can be created with specific permissions
Checking Permissions
import requests
url = "https://your-instance.erpnext.com/api/method/frappe.client.get_value"
headers = {
"Authorization": "token api_key:api_secret"
}
data = {
"doctype": "Customer",
"fieldname": "name",
"filters": {"name": "CUST-00001"}
}
response = requests.post(url, headers=headers, json=data)
if response.status_code == 403:
print("Insufficient permissions")
else:
print(response.json())
If you receive 403 Forbidden errors, verify that the API user has the required role permissions for the DocType being accessed.
Security Best Practices
Use HTTPS
Always use HTTPS in production to encrypt API credentials and data in transit.
Rotate API Keys
Regularly rotate API keys and secrets, especially if they may have been compromised.
Limit Permissions
Create dedicated API users with minimal required permissions using custom roles.
Monitor Access
Enable logging and monitor API access patterns for suspicious activity.
Use Environment Variables
Never hardcode API credentials in source code. Use environment variables or secure vaults.
Implement IP Whitelisting
Consider restricting API access to specific IP addresses when possible.
Environment Variables Example
Store credentials securely:
ERPNEXT_URL=https://your-instance.erpnext.com
ERPNEXT_API_KEY=your_api_key_here
ERPNEXT_API_SECRET=your_api_secret_here
Troubleshooting
401 Unauthorized
- Verify API key and secret are correct
- Check that the Authorization header is properly formatted
- Ensure the API user account is enabled
403 Forbidden
- Verify the user has required role permissions
- Check DocType-level permissions in Role Permission Manager
- Ensure the user is not restricted by user permissions
Session Expiry
- Implement token refresh logic for long-running applications
- Use API keys for persistent access instead of session tokens
- Handle 401 responses by re-authenticating
Next Steps
- Explore the API Overview for request/response formats
- Review ERPNext user and role management documentation
- Join the ERPNext community forum for authentication support
