How EspoCRM API users keep integrations separate from people
An integration that reads or writes CRM records should never sign in with a person's login. When a middleware job, ERP sync, marketing connector or custom script runs under an employee's account, every change it makes is attributed to that person, its access follows that person's role, and it stops working the day they leave or change jobs. In EspoCRM the fix is an API user, a dedicated user type whose permissions come from the roles assigned to it, so the integration gets exactly the entities and actions it needs and nothing more. Teams usually need this as soon as a second system starts writing to the CRM, for example a middleware platform that creates leads, an ERP that pulls accounts and invoices, a marketing tool that updates contact consent, or a script that runs on a schedule.
The EspoCRM REST API accepts three kinds of authentication for these users: API key, HMAC and basic authentication. According to the EspoCRM API documentation, HMAC is the most secure of the three, and basic authentication is not recommended. Because the choice is made per integration, the practical decision is which method each connected system can sign requests with, and whether the calling platform can keep a secret safely. Confirm with each vendor or internal team which methods their connector supports, and record that answer alongside the role the account will hold. Also confirm how your EspoCRM version exposes API user creation and credential generation in the administration area, since the screens and options should be checked against the version you run rather than assumed from older guides. The EspoCRM API documentation is the natural starting point for the request formats and authentication headers.
Which authentication method fits which integration
This table compares the three REST API authentication methods EspoCRM supports across strength, setup effort, server-to-server fit and the documentation's guidance. Read each row against the integration you are building, and treat the owner row as the decision that prevents credentials from outliving the project that created them. The main takeaway is that HMAC is the method the EspoCRM docs call the most secure, while basic authentication is documented as not recommended.
| Factor | API key | HMAC | Basic authentication |
|---|---|---|---|
| Security strength | Secure when the key is stored and rotated well, but a leaked key works until it is replaced | Described in the EspoCRM docs as the most secure method of the three | Described in the EspoCRM docs as not recommended |
| Setup effort | Low: generate a key for a dedicated API user and send it in a request header | Higher: the client must compute a signature for each request, so the integration team needs to implement signing | Low: encode a username and password, which is why it is the easiest to get wrong |
| Fit for server-to-server calls | Good for scheduled jobs and middleware where the secret stays on the server | Good fit for server-to-server integrations where the team can maintain signing code | Poor fit: credentials travel with every request and tie the integration to a user password |
| Credential form | A single key tied to one API user | A key pair tied to one API user, with the secret never sent in the request | A username and password of an API user |
| Recommendation in EspoCRM docs | Supported method for API users | Recommended method when security is the priority | Not recommended |
| Who should own the credential | The integration owner, recorded with the API user name, system and renewal date | The integration owner, with the signing code and secret held in the same secret store | Avoid for new work. If it exists today, the integration owner should schedule its replacement |
| Where the secret lives | A secret store or the EspoCRM App Secrets feature, never in formula or workflow text | Secret store on the calling server, never in client-side code | Would otherwise sit in configuration files, so keep out of source control |
| Rotation and revocation | Regenerate the key and update each caller, then confirm the old key no longer works | Rotate the secret and update signing configuration on the caller | Change the password of the API user, which also affects any other caller using it |
Setting up an integration account in EspoCRM
This sequence produces a dedicated API user with a narrowly scoped role, a working credential stored outside the CRM, a verified read and write, and a named owner who can answer for the account.
Confirm the integration's data needs
Before touching the admin console, the integration owner and the CRM administrator list each entity, field and action the integration needs, such as reading Accounts and creating Leads. Anything not on this list stays out of the role. Write the list in the change ticket so the role can be reviewed against it later. The step is done when both people sign the same list and no entity is marked as needed for convenience.
Create a dedicated API user
In Administration, open the user management area and create a new user with the API user type rather than a regular user with a generic login. Use a name that identifies the system and its purpose, for example an illustrative name such as sync-erp-accounts, so audit logs show which integration acted. Do not attach the account to an administrator role or reuse a person's account. The step is done when the user exists with the API type and no admin privileges.
Assign a least-privilege role
Create a role for this integration instead of editing a shared one. Grant read, create or edit permissions only on the entities identified in the first step, and set every other entity to no access. Check the scope levels carefully, since team or own scopes narrow what the account sees, while all scope exposes every record. Link the role to the API user and save. The step is done when the role appears on the user and the permission grid matches the approved list.
Generate and store the credential
Generate the API key or HMAC secret from the API user's record. The EspoCRM API documentation describes HMAC as the most secure of the supported methods and basic authentication as not recommended, so choose HMAC where the calling system supports it. Copy the secret once into the integration's secret store, not into a ticket, chat or formula. Avoid placing it in plain configuration files on shared servers. The step is done when the credential works from the integration host and is recorded in the secret store with its location noted.
Test one read and one write
From the integration host, make one read request against an entity in scope and confirm the returned records match expectations. Then make one write to a test record that the integration is allowed to change, and confirm it appears in EspoCRM and in the record's stream. Keep the request and response samples for the change file. The step is done when both calls succeed with the intended credential and no request is made with a personal login.
Confirm the account cannot reach unrelated data
Repeat the request pattern against an entity the role does not grant, and against records outside the team or scope the role allows. The expected result is a denied or empty response, not data. Also attempt a basic action such as an admin endpoint to confirm it is refused. Record each result. If any unrelated entity is readable, return to the role and correct it before the integration goes live. The step is done when every negative test is refused.
Record the owner and review schedule
Document the account name, its role, the credential location, the business owner who approves changes and the technical owner who rotates the secret. Store this record with the integration's runbook. Ask your team to confirm the review cadence and the rotation procedure in advance, since the platform documentation does not set one for you. The step is done when the owner, the rotation contact and the role change history are all written down and the account is marked as active in the inventory.
Security controls for API users
An API user in EspoCRM is a standing identity that can read and write customer data without a person signing in. The controls below cover who the account is, what it can reach, where its secrets live, where it can connect from, and how its activity is reviewed. Each one closes a different path an attacker or a misconfigured integration could use.
Keep admin roles off API users
An API user inherits the permissions of the role assigned to it, so an administrator role turns a leaked key into full control of the instance, including entity definitions, users and settings. Give each integration a role that does only the job it needs. Before go-live, confirm that no integration account is assigned a role with administrative rights, and check this again whenever a role is edited. Admin work should stay with named admin accounts.
Scope roles by entity and team
Permissions in EspoCRM are set per entity and per access level, such as all, team or own records. An integration that syncs accounts from one business unit should not be able to read every lead in the system. Define the entities the integration touches, choose the narrowest access level that still works, and test with sample records from more than one team. Keep the role list short so reviewers can read it.
Never reuse a staff login
Connecting an integration with a person's own username and password ties its activity to that person, breaks when they leave or change roles, and gives the integration their full access. A dedicated API user with its own role keeps the audit trail separate and lets you disable the integration without affecting staff. Ask each integration owner to name the API user and role they will use before the build starts.
Store credentials outside code
API keys and HMAC secrets should never appear in source control, workflow definitions, scripts or chat threads. Keep them in a secrets manager you already operate, or in EspoCRM App Secrets when the credential is used by formula logic or Send HTTP Request actions inside EspoCRM. Confirm who can view or rotate each secret, and record where every copy lives so a rotation does not miss one.
Restrict source addresses
The IP whitelist limits where logins are accepted, and a fixed set of integration servers can often be allowed by address. Exceptions for portals and API users have to be planned explicitly, and the proxy setup determines which address EspoCRM sees. Confirm the real client address reaches the application through your reverse proxy before you rely on an allowlist, and test a request from an address outside the list.
Log and review API activity
Without regular review, a compromised integration can read records for months before anyone notices. Set a schedule for checking what each API user did, compare it with the integration's expected volume and entities, and alert on access outside working hours or from unexpected addresses. Confirm with your EspoCRM hosting team where access logs are kept, how long they are retained, and who can read them.
How to rotate API keys and HMAC secrets without downtime
Rotate by overlap, never by replacement. The safe sequence is to create a new credential for the API user, deploy it to the integration, confirm that requests are arriving under the new credential, and only then revoke the old one. Each step needs a named check: the integration should show successful calls with the new key, and the EspoCRM API user's activity should show no remaining traffic on the old one before anyone deletes it. Revoking first is the most common cause of a rotation outage, because every system still holding the old value fails at once.
The sequence breaks most often where an integration caches a secret. Middleware, iPaaS connectors, scheduled scripts and SDKs frequently read the key once at startup and keep it in memory or in a configuration file that a deployment does not reload. Before the first rotation, list every place each credential is stored and confirm how each consumer picks up a changed value, whether by restart, reload or re-reading a secrets store. For HMAC signing, confirm which clock and signing parameters the client uses, since a mismatch looks like an authentication failure rather than a stale secret. Confirm the exact behavior of your EspoCRM version and HMAC setup with the EspoCRM API documentation before you rely on it in a runbook.
Shared accounts make all of this harder. If three integrations authenticate as one API user, rotating its credential forces a coordinated change across all three, and no one can tell which consumer still uses the old value. Give each integration its own API user with a role scoped to what that integration needs, so each credential can be rotated on its own schedule. Then record an owner, a system name, the rotation interval and the date of the last rotation for every API user, and set a review date that someone is accountable for. Ask your team to confirm how they will be notified when an automated rotation or a revocation fails.
How API user setup differs by deployment
On your own servers, you control every layer that sits between an integration and the EspoCRM application. That includes the web server, the TLS termination point, any load balancer, and the database host. API users are created and scoped in the admin interface like any other user, but the network path to the API is yours to design. EspoCRM supports Apache, Nginx and IIS, and the server configuration docs require PHP and a database version that you install and patch yourself. Background jobs depend on cron or a scheduled task, so credential rotation jobs and integration retries also depend on a host you maintain.
- Reverse proxy behavior: Confirm that the proxy passes the full request path and query string unchanged. Any rewrite that alters the URI will break HMAC signatures, because the signature covers the request as the server sees it.
- Header forwarding: Decide which headers the proxy forwards, including the host header and any headers your integration signs. Test with the exact proxy configuration you will run in production.
- Secret storage: API keys and HMAC secrets live in the EspoCRM database for your instance, so database backups contain credential material. Restrict who can read backup archives.
- Backups: Include the database and file storage in one restore plan, and test that a restored instance accepts existing keys or that you have a documented reissue step.
- Access to the API port: Place the API behind your network controls and decide whether integration traffic reaches EspoCRM directly or through an internal gateway.
Before go-live, send a signed test request through the production proxy path and confirm the server accepts it.
With EspoCRM Cloud, the hosting, the web server layer and the database are operated by the EspoCRM team, so you do not manage the reverse proxy or the server itself. The pricing page lists EspoCRM Cloud as a per-user subscription with the Advanced Pack included in all cloud plans. You still create dedicated API users and assign role-scoped permissions inside your instance, and those decisions are your responsibility regardless of hosting. What changes is the set of infrastructure details you can inspect and alter, so your integration design should rely only on the API surface and documented behavior.
- Proxy and header control: Confirm with the vendor which headers reach the application and whether any intermediary alters them before they reach EspoCRM. Do not assume your own proxy rules apply.
- IP restrictions: Ask how IP allowlisting interacts with integration traffic, because integration servers often have fixed egress addresses that must be listed.
- Secret handling: Keys still belong in your integration platform's secret store, not in scripts. Confirm how the vendor handles backups that contain credential material.
- Backups and restores: Ask what backup and restore options are available to you and how a restore affects existing API keys.
- Plan and user count: API users may count toward licensed users. Confirm this in the pricing terms before you create several integration accounts.
Before relying on a hosted instance, ask the vendor to describe in writing every layer that sits between your integration and the API.
The installation script for Ubuntu, Debian and Linux Mint deploys a Docker-based stack with Nginx and MariaDB, with optional Let's Encrypt certificates and a command.sh utility for backups, restores and upgrades. This model keeps the proxy inside the stack, so header handling and TLS behavior are defined by configuration files that the script creates. You manage the host, the containers and the volumes, which means credential material sits in the database volume and in whatever backup files command.sh produces.
- Bundled Nginx: Review the generated Nginx configuration before go-live, especially any rules that rewrite paths or change forwarded headers, since HMAC verification depends on them.
- Certificate handling: If you enable Let's Encrypt, confirm that renewal runs and that the integration endpoint uses the same hostname your signing code uses.
- Volume and backup scope: Confirm which volumes command.sh backs up. Credential material in the database must be included in restore tests.
- Upgrade effect on keys: Check the release notes for each upgrade to confirm that existing API keys and HMAC secrets remain valid.
- Container secret injection: Pass integration secrets to consuming systems through your secret manager, not through environment files committed to version control.
After each stack change, rerun a signed request and an API key request, because a proxy change can break one method and not the other.
Questions teams ask before setting up EspoCRM integrations
What does an EspoCRM integration project actually involve?
An integration project covers agreeing which systems exchange which records, designing the API user and role permissions each integration needs, choosing the authentication method, building and testing the calls, and documenting how credentials are issued and rotated. Work usually spans the CRM configuration, the connected system, and the test runs that prove both sides behave correctly. The main effort drivers are the number of integrations, the number of entities each one touches, how many role variants the permissions require, and how much testing the data flows need before go-live.
What drives the effort of an EspoCRM integration up or down?
Effort rises with four factors: how many integrations exist, how many entities and fields each one reads or writes, how complex the role model is (for example, team-scoped access for several sales regions), and how thorough testing must be. Integrations that only read data are simpler than those that create or update records, because writes need validation, duplicate handling and error recovery. Ask for each integration to be listed with its direction, entities, permissions and test cases so the quote reflects the real surface.
Can our internal team set up EspoCRM API users and integrations on its own?
Yes, many teams do, provided they have engineers who understand REST APIs, role-based permissions and secret handling. EspoCRM documents API users, API key, HMAC and basic authentication, so the mechanics are accessible. The hard parts are usually permission design and long-term operations: deciding the minimum role for each integration, keeping credentials out of scripts, and rotating them without breaking production. A partner is most useful when the internal team lacks time, or when a review of the design is needed before rollout.
What does the work need from our staff?
Plan for a named business owner who signs off on which records each integration may access, a technical owner who runs the connected system, and access to a non-production EspoCRM instance for testing. You will also need current documentation of your sales and service processes, field definitions, and the systems that will connect. Without a test instance, permission and data-quality problems tend to surface in production. Confirm who approves changes to API user roles before the project starts.
How long does an EspoCRM integration take?
Duration depends on the number of integrations, the number of entities involved, the complexity of role design and how much testing and sign-off the organization requires. The EspoCRM documentation does not give project durations, so the reliable approach is to ask for a timeline tied to a written scope with named milestones: design, build, test, and go-live. Single read-only integrations are typically much quicker to settle than multi-system bidirectional syncs with custom fields and error handling.
What should a fixed-scope quote for EspoCRM integrations list?
A fixed-scope quote should list each integration with its source and target systems, data direction, entities and fields, the API user and role for each one, the authentication method, and the test cases that will prove it works. It should also state what is excluded, such as changes to the connected system, extensions that must be purchased separately, and hosting. Ask how credentials will be stored and rotated, what documentation will be handed over, and what post-go-live support is included or offered as a separate retainer.
Do the EspoCRM open-source edition and official extensions affect integration cost?
Yes. EspoCRM is licensed under AGPL-3.0 and the open-source edition can be self-hosted for free, according to the EspoCRM pricing page. Some integrations depend on official extensions, and the Advanced Pack, which provides workflows and Business Process Management, is included in all EspoCRM Cloud plans. Confirm in the quote which features require an extension, whether you are running self-hosted or cloud, and who is responsible for licensing decisions. Hosting costs are separate from the implementation work.
Limits to confirm in your environment
The API user type, its role-scoped permissions and the authentication method all depend on the EspoCRM version you run and the systems on the other end of the integration. The cards below list the points to confirm with the vendor documentation and in a test instance before any integration account reaches production.
Permission behavior per role version
Role-scoped permissions for API users are the core of the access model, but the exact behavior of each entity, field and action level can change between releases. Confirm in the API documentation for your version which scopes apply to API users, how team-inherited access is evaluated for them, and whether any action is granted implicitly. Test each permission with a real request in a staging instance, not only in the role editor.
How the API user type behaves by version
Confirm how your chosen EspoCRM release creates, labels and restricts API users, including whether they can sign in through the web interface and how they interact with IP restrictions. Behavior on the 10.x line may differ from earlier versions, so check the release notes for the exact version you plan to deploy rather than assuming the behavior carries over.
Authentication method support by target system
EspoCRM documents API key, HMAC and basic authentication. HMAC is described as the most secure of these, but the receiving system must be able to produce the signature. Confirm whether the target integration supports HMAC signing, how it builds the signed string, and whether it can rotate keys without downtime. If it cannot sign requests, plan an API key scheme with a documented rotation schedule.
Rate limits and request size behavior
Neither the EspoCRM documentation nor this plan establishes numeric rate limits or maximum request sizes for the API. Ask your implementation team to measure throughput and payload limits on your server stack, including PHP settings and any proxy or gateway in front of EspoCRM. Also confirm how large batch writes behave, and whether the integration needs retry logic for timeouts or throttling from your own gateway.
Background job and webhook timing
Some integrations depend on work that runs in the background, such as scheduled jobs or workflows that fire after a record is saved. Confirm that cron or the scheduled task runner is active on your server, since the EspoCRM server configuration requires it for background jobs. Check how long a change takes to appear in the downstream system, and whether your integration tolerates that delay.
Log visibility for API activity
Confirm what EspoCRM records for API requests, which user and IP address are captured, and where logs are stored and rotated. Check whether your logging pipeline can separate integration traffic from human sessions, and whether a retained log is enough to investigate a misused key. Ask your security team to define the retention period before rollout, since the platform default may not match your policy.
How DeployOpen works on this
DeployOpen plans, builds, documents and supports EspoCRM integration accounts inside your own infrastructure. Each engagement is fixed-scope, with the API user roles, authentication method and credential rotation agreed in writing before any work starts.
How we scope
- Inventory every system that will call EspoCRM and the records, fields and actions each one needs.
- Agree the API user roles, team boundaries and authentication method for each integration in the written scope.
- Confirm who owns each credential, where it is stored and how often it will be rotated.
How we build
- Create dedicated API users with role-scoped permissions, separate from any administrator or daily-use account.
- Configure API key or HMAC authentication, store secrets outside formulas and workflows, and test denied requests.
- Test each integration against a non-production instance, including permission boundaries and error handling.
How we hand over
- Document each API user, its role, its permissions, its owner and the systems that depend on it.
- Provide a rotation runbook covering key replacement, cutover steps and how to revoke a compromised credential.
- Walk your administrators through the access model so they can review and change integration accounts safely.
How we support
- Review integration accounts and their permissions on a schedule agreed in your scope or retainer.
- Support credential rotation and permission changes when systems, teams or vendors change.
- Ongoing support, upgrades and continuous testing are available as retainers, priced from your written scope.
