ERPNext as an OAuth 2 provider for apps

When an OAuth 2 provider setup in ERPNext makes sense

An internal app, customer portal or integration often needs to call ERPNext on behalf of a person. The alternative is to store a shared ERPNext username and password or a long-lived key inside that app, which makes access hard to trace and hard to revoke. Using ERPNext as an OAuth 2 provider means the calling app registers as an OAuth client, the person approves that app once, and the app then uses a bearer token that ERPNext issues for that user. The token proves who is calling, and it can be revoked without changing the user's password. This page covers how to register clients, handle tokens and scopes, and when an API key is the better choice instead.

OAuth 2 only handles authentication and token issuance. It does not widen what a user can see. Once a token is issued, ERPNext's role permissions, user permissions and field-level rules still decide which DocTypes, records and fields the caller can read or change, exactly as they do in the desk. Before go-live, test each integration with a low-privilege test user and confirm the results match that user's rights in the desk, since a broad System Manager role makes the token broad too. Also confirm which OAuth client settings, token lifetimes and scope options exist in your ERPNext version, because these details change between releases and should be checked against your own installation.

Do not confuse this with Social Login Key. The Frappe documentation on Social Login Key covers the reverse direction: ERPNext users signing in through external providers such as Google, Microsoft or a custom OpenID Connect endpoint. This page covers ERPNext acting as the identity source for other applications. Choose OAuth 2 when a person must be identified and the app acts for that person. Choose an API key when a server-to-server job runs without a user session and a service account with tightly limited permissions is acceptable.

OAuth 2 clients, bearer tokens or API keys: which fits which integration

This table compares OAuth 2 clients, the bearer tokens they issue, and API keys across caller type, approval, revocation, scope limits and operating cost. Read each row against the integration you are building, then confirm the behavior in the ERPNext version you run, because token and key handling has changed between releases.

Decision point	OAuth 2 client with user-delegated tokens	API key tied to a user or service account
Typical caller	An internal app acting for a named person who signs in and approves access	A scheduled job, script or service that runs without a person present
Who approves access	The signed-in user consents at the authorization step, and the client is registered by an administrator	An administrator generates the key for a user or service account, usually with no per-request consent
How access is revoked	Revoke the client, revoke individual tokens, or disable the user who granted consent	Regenerate or delete the key on the user record, which stops every integration using it at once
How scope is limited	Limited by the requested scopes and by the roles and user permissions of the consenting user	Limited by the roles and user permissions of the account the key belongs to, with no separate scope list
Main operational trade-off	Token expiry and refresh logic must be built and tested, but each person's access is traceable	Simple to set up, but a shared key is hard to attribute and rotating it breaks every caller
Logging and attribution	Actions can be traced to the consenting user and the client	Actions are attributed to the account, so a person behind a shared key is not visible
When to choose it	Users should see and act only within their own access, or several apps need separate consent	Unattended automation under a dedicated service account with a tightly scoped role
What to confirm in your version	Available scopes, token lifetimes, refresh behavior and the client registration screen	How keys and secrets are generated, shown once, and whether they can be restricted by IP or expiry

Registering ERPNext OAuth 2 clients and testing them

This sequence takes an internal app from a stated data need to a registered OAuth client that has been tested for both allowed and denied records, with a documented way to revoke access. Each step ends with a check you can record before the client goes anywhere near production.

Define each caller and its data needs
List every app or integration that will authenticate against ERPNext, the DocTypes and fields each one reads or writes, and whether it acts for a person or runs as a background service. Owners from the business and the app team should sign off on this list. Done means each caller has one row that names its DocTypes, operations (read, create, update, submit) and the people who will approve its access. Any caller that needs a broad, unscoped view should be flagged for review before you continue.
Create a dedicated integration user
Create a separate user for each caller that acts as a service, rather than reusing a person's account or the Administrator account. Assign only the roles that the DocTypes in step one require, and add no System Manager role. Check the role names, user type and role profile options in your version, since menus and labels change between releases. Done means the user has a documented role list that a second reviewer has read and accepted.
Register the OAuth client with exact redirect URIs
Register the client in ERPNext using the OAuth client record in your version, entering the exact redirect URIs the app will use, with no wildcards or extra paths. Record the client ID and any secret in your secrets manager, not in tickets or chat. Confirm which grant types and scopes the form offers in your version and select only what the caller needs. Done means a test request to an unlisted redirect URI is rejected by the authorization server.
Run a test authorization for one user
Sign in as a test user who holds the same roles and user permissions as the production user the caller will act for. Walk through the authorization code flow from the calling app and confirm the consent screen and token response behave as your version documents. Record the token lifetime and the scopes granted. Done means you have a token for that user and a log entry showing which client and user were issued it.
Confirm the token returns only permitted records
Using the token, call the API for a list of the DocType in scope and compare the results against the same list viewed in the Desk by that user. Check that User Permissions, role permissions and field-level permissions apply to API responses in your version, and that the counts match. Done means the API result set equals the Desk result set for that user, and any mismatch is logged as a blocker.
Test a denied record and a denied action
Pick a record that the test user must not see, such as a document for another company or territory, and request it with the token. Repeat with a write the role should not allow, such as cancelling a submitted document. Done means both requests return an authorization error and nothing is written. Keep the request and response pairs as evidence for the access review.
Document and rehearse revocation
Write down how to revoke the client, its tokens and the integration user, and who is authorized to do it. Rehearse revocation in a test environment and confirm that the previously issued token stops working. Confirm the exact steps in your version, since token revocation options and the place they appear may differ. Done means the runbook names the owner, the steps and the check that proves access is gone.

Security risks to design out before an ERPNext token goes live

Most OAuth failures in an ERPNext integration come from configuration choices made in the first week, not from the protocol itself. The cards below cover the places where a client, a user account, a token or a script can quietly widen access. Check each one before the first token is issued, then again when staff or integrations change.

Redirect URI mismatch and open redirects

The redirect URI registered for an OAuth client decides where authorization codes are sent after login. If the registered value is a wildcard or a broad path, an attacker can steer a user's code to a host they control. Register exact HTTPS callback URLs for each client, one per environment, and reject any request whose redirect URI does not match the registered value character for character. Test with a deliberately altered callback to confirm ERPNext refuses it.

Over-broad integration users

An integration that logs in as a user with System Manager rights can read and change almost everything on the site, and a token issued for that user inherits the same reach. Create a dedicated integration user for each app, assign only the roles and user permissions its documents need, and keep it out of the groups that hold administrator rights. Review the effective permissions with a test account before go-live.

Long-lived tokens stored in browsers

A bearer token is valid for whoever holds it, so a token kept in local storage or a long-lived cookie can be read by any script that runs in that page. Keep token lifetimes short, store tokens server-side where the app allows it, and use the refresh flow rather than extending access. Ask the app team where each token is kept and whether a logout clears it.

Tokens leaking through logs and query strings

Tokens placed in URLs end up in web server access logs, proxy logs, browser history and error reports. Send tokens only in the Authorization header, configure reverse proxies and application loggers to mask that header, and disable debug output in production. Search your log platform for the token prefix after the first test run to confirm nothing was written in clear text.

Missing revocation when staff leave

When an employee leaves, disabling the ERPNext user account may not stop an integration that holds a valid token for that person. Define who revokes OAuth clients and tokens in the offboarding checklist, and make sure a disabled user cannot obtain new tokens. Confirm with a test user that an existing token stops working after revocation, and record the owner of each client so that orphaned clients can be found.

Scripts that bypass permissions

Server Scripts run Python on document events or as API endpoints, and a script that calls database functions with ignore-permission flags can return or change records the caller should never reach. Keep server-side logic in a reviewed custom app rather than ad hoc scripts, and check that each endpoint enforces the same permissions as the standard API. Note that scripts are disabled by default from version 15 and must be enabled with the server_script_enabled setting, so confirm whether that setting is on in your environment.

How ERPNext role and user permissions apply to token callers

A token does not grant its own rights. It acts for the user who authorized it, so the role permissions, user permissions and field-level rules that govern the desk should also shape what an API call returns and what it can change. Before you register a client, decide which user each integration will act as, and review that user's roles, user permissions and perm-level restrictions the same way you would review a person who logs in to the desk. A client that reads customer records through a user limited to one company should never see another company's invoices, whatever the OAuth scope says.

A service account needs its own narrowly scoped roles rather than a borrowed personal login or a broad role such as System Manager. Create a dedicated user for each integration, assign only the roles that DocType access requires, add user permissions to restrict records where your access model calls for it, and exclude sensitive fields through perm levels. Confirm the exact behavior in your version on three operations: list calls, which filter results; detail calls, which return a single record; and write calls, which must respect submit and cancel rights. Test each one with a restricted user before go-live, and record what each response contains.

Scopes are only useful if they map to real limits. If your version supports scopes for the OAuth client, check that a token with a read-only scope cannot create or update documents, and that a scope limited to one module cannot reach another. Where it does not enforce a scope, rely on the user's roles instead and document the gap. Custom server logic that changes behavior, such as a server script that alters a response or validates a write, depends on the server script setting described in the Frappe Framework server script documentation. From version 15, that setting is disabled by default, so confirm whether it is enabled on your site and whether your hosting plan allows it.

Setup differences by ERPNext hosting model

Frappe Cloud shared sites run on a platform managed by Frappe, so many infrastructure decisions are fixed by your hosting plan. The OAuth client is created on the site itself, but the options you can change depend on what the plan exposes. Confirm each item below before you design the authentication flow.

Where the client is set: Create the OAuth client record in the site desk if your user type and plan allow it. Confirm that the people who will maintain the client hold the roles they need.
TLS and callback URL: Frappe Cloud manages certificates for the domain the site serves. Confirm that your public callback URL uses that same domain and that custom domains are supported on your plan.
Secret storage: The client secret is stored in the site database. Confirm who can read it, how it is rotated, and whether the platform offers any secret storage outside the site.
Server scripts: Public shared benches do not allow server scripts. Any custom token logic must live in a custom app, a separate service or the calling application, so confirm this before relying on a script.

Check the plan's feature list and the site settings against this tab before you commit the callback design.

Dedicated Frappe Cloud servers give you more control over the bench and its configuration than shared sites, but Frappe still operates the underlying infrastructure. The client is registered in the site desk in the same way as on shared sites, so the differences lie in what you can configure at the server and domain level. Confirm these points with Frappe against your plan and your ERPNext version.

Where the client is set: Create the client in the site desk, as on shared sites. Confirm whether your plan lets you deploy custom apps that add OAuth behavior.
TLS and callback URL: Confirm who issues and renews certificates for custom domains, and whether the public callback URL can use a domain your organization controls.
Secret storage: Client secrets remain in the site database. Confirm whether you can keep other secrets in server-level configuration and how access to that configuration is logged.
Server scripts: Server scripts are disabled by default from version 15 and must be enabled with the server_script_enabled setting. Review the Frappe Server Script documentation and confirm that your dedicated bench permits enabling it.

Ask Frappe to confirm each item in writing before the callback design is final.

With bench on Linux, your team controls the web server, certificates, process manager and secret handling, so every item in this tab is a decision you own. The client is still created in the ERPNext desk after the site exists, but the callback URL, TLS termination and secret storage follow your own infrastructure standards. Confirm the configuration keys below against the documentation for your installed version.

Where the client is set: Create the client in the site desk once the site is installed. Plan the callback URL so it matches the public address of your reverse proxy.
TLS and callback URL: Terminate TLS at your proxy or load balancer, and set the public host and protocol in the site configuration so generated URLs use HTTPS. Confirm the exact keys for your release.
Secret storage: Keep the client secret in the database, and restrict access to site_config.json, the database and any backups, because all of them can expose it. Store the calling application's copy in your secrets manager.
Server scripts: Enable server scripts only if your team accepts the review effort, by setting server_script_enabled in the site configuration. Scripts run with the server's permissions, so treat them as code.

Confirm each setting on a test site before you apply it to production.

The frappe_docker repository provides production images and Compose files with services for MariaDB, Redis, background workers, the scheduler, Socket.io and Nginx. Its single-file demo setup is intended for short-lived evaluation only, so an OAuth design tested there should be moved to the production layout before go-live. Configuration arrives through environment variables and mounted files, which changes where secrets are kept.

Where the client is set: Create the client in the site desk after the stack is running, and record its settings in your deployment notes so it can be recreated in a new environment.
TLS and callback URL: Terminate TLS at the Nginx service or an upstream proxy, and set the public host so callback URLs are generated with HTTPS. Confirm the variable names in the repository documentation for your image version.
Secret storage: Do not place client secrets in Compose files committed to version control. Use Docker secrets, an external secrets manager or injection from your CI system, and confirm how the database volume is backed up.
Server scripts: The same version rules apply, so set server_script_enabled deliberately in the site configuration and confirm the image version first.

Verify the callback flow in a staging stack built from the production layout, not the demo file.

Limits to confirm in your ERPNext version before you build

OAuth 2 behavior in ERPNext depends on the exact major version you run, and that version has a support window with its own rules. The cards below list the limits to verify in writing before you design clients, scopes and token handling around them.

Supported OAuth flows and token lifetimes

Confirm which grant types your ERPNext version exposes for third-party clients, and how long access and refresh tokens live by default. Token lifetime drives how often a service account must re-authenticate, and it determines whether a long-running integration can operate without a human present. Ask for the default values and where they are configured, and test them on a staging site running the same version.

Scope granularity

Find out whether the version offers named scopes that map to DocTypes or whether access is effectively governed by the user's roles and permissions. Coarse scopes mean a token can reach more data than the integration needs, so the mitigation moves to the user the token represents. Write down the access each integration needs and test that a token cannot read or change records outside it.

Refresh and revocation behavior

Confirm how refresh tokens rotate, how long they remain valid, and how an administrator revokes a single client or every token issued to a user. Revocation must work when an employee leaves or when a client secret is exposed. Test the full path: revoke, confirm the next API call fails, and confirm that the audit trail records the event.

API rate limits

Check whether the version or your hosting setup applies rate limits to API calls made with OAuth tokens. Background sync jobs that page through large DocType lists can hit limits that interactive users never see. Measure the request volume your integration will generate, then ask whether limits are set in ERPNext, in the reverse proxy, or by the hosting provider.

Support plan coverage

Frappe's supported versions policy ties warranty coverage to running a listed version with a matching Frappe Cloud support plan. If you self-host, confirm with Frappe or your implementation partner what support applies to your version and to any custom OAuth code you add. Ask for this in writing before you choose a version for the integration.

Whether a custom app is required

Determine whether the standard OAuth provider covers your client registration, consent and token needs, or whether a custom app must add scope logic, client metadata or token endpoints. A custom app adds code you must upgrade with each ERPNext release and test after every minor release. Decide this during design, because retrofitting it after clients are live is costly.

OAuth 2 provider questions buyers ask before hiring help

What drives the cost and effort of an OAuth 2 integration with ERPNext?

The main drivers are the number of client applications, the grant types each one needs, and how many scopes and DocTypes each client must reach. Each additional client adds registration, redirect URI handling, token lifetime decisions and testing. Effort also rises when external identity providers, role mapping or audit logging must be designed. Ask for a written scope listing each client, its grant type, the data it reads and writes, and who signs off on access. Confirm whether the quote covers testing against your own test environment and handover documentation, since those are separate line items.

Can an internal team set up ERPNext OAuth 2 without outside help?

Yes, a team with Frappe experience and a clear design can do it, but the work is more than registering a client. The team needs to understand how Frappe issues tokens, how roles and permissions apply to the token's user, and how scopes map to what the client may actually do. Most in-house gaps show up in security review rather than in the first login test. Consider outside help if no one on the team has operated a Frappe site in production, if several clients must share one identity model, or if the security team requires an independent review of the design.

How long does a scoped OAuth integration usually take?

Duration depends mainly on how many clients exist, which flows they use, and how many identity owners must approve access. A single client using one authorization flow is a much smaller job than several internal services with different scopes and token lifetimes. Timelines also depend on how quickly your identity owners, test environment and security reviewers respond. No fixed figure applies across environments, so ask any provider for a timeline tied to a written list of clients, flows and review steps, with the dependencies named.

What does the client need to provide for an OAuth 2 project?

The client typically provides four things. First, named identity owners who decide which users and roles each application may act for. Second, a non-production ERPNext site that mirrors the production roles and permissions, so tokens can be tested safely. Third, a dedicated integration user whose roles are limited to what the client needs, rather than a System Manager account. Fourth, security sign-off on scopes, token lifetimes, redirect URIs and logging. Ask the provider to confirm in writing which of these they expect you to supply and which they will prepare.

When are API keys a better choice than OAuth 2 in ERPNext?

API keys suit a single trusted server-to-server integration that acts as one service account and does not need per-user consent or delegated access. OAuth 2 suits applications where users sign in and the app should act only within that user's permissions, or where many clients need separate, revocable credentials. API keys are simpler to set up but usually tie access to one user and are harder to rotate without disruption. Decide based on who the calling application acts for, how often credentials must be revoked, and how the security team wants access logged.

What should a written OAuth 2 scope include before work starts?

A useful scope lists every client application with its owner, the grant type it uses, the redirect URIs it will register, and the ERPNext DocTypes and actions each client may reach. It should state token lifetime and refresh behavior, how revocation works, and where access events are logged. It should also name the test environment, the integration user, and the acceptance tests that show each client sees only what it should. Ask for the deliverables and handover documents in the same list, so you can compare proposals on equal terms.

Does an OAuth 2 provider setup cover compliance evidence?

Setup can produce evidence that supports a compliance review, such as documented client registrations, scope definitions, test results and access logs. It does not make the system compliant on its own, and it does not produce an audit report. Independent auditors and certification bodies decide whether controls meet a given framework. Ask the provider which evidence artifacts they will deliver, and confirm with your auditor which of them the review will accept.

How DeployOpen scopes and supports ERPNext OAuth integrations

DeployOpen approaches OAuth 2 access to ERPNext as part of a written, fixed-scope engagement that covers the clients, scopes, token lifetimes and fallback credentials your integrations need. Work runs inside your own infrastructure, from a planning review through to a documented handover and optional ongoing support.

How we scope

We list each internal app or integration that will authenticate against ERPNext and the data it must read or write.
We map each integration to the least-privilege roles and permissions it needs, and record which ones must stay out of scope.
We confirm which ERPNext version and deployment model you run, so the scope matches the OAuth behavior of that release.

How we build

We register the OAuth clients in ERPNext, configure redirect URIs and scopes, and keep client secrets out of source code.
We test the authorization flow, token issuance, refresh and revocation in a non-production site before any cutover.
We decide where API keys remain the better fit for server-to-server jobs and configure them with the same role boundaries.

How we hand over

You receive a written register of clients, scopes, token lifetimes, owners and the permissions each integration holds.
We document the test cases used to confirm access denial for roles outside each integration's scope.
We hand over runbooks for rotating client secrets, revoking tokens and responding when an integration is decommissioned.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, so OAuth clients are reviewed after each ERPNext release.
We recheck client registrations and scopes when integrations change, and when your ERPNext version moves to a new supported release.
Quotes follow from the written scope, and you should ask for the one-time and recurring effort to be listed separately.

Using ERPNext as an OAuth 2 provider for other apps