EspoCRM app secrets: store API keys safely

Why EspoCRM app secrets matter for integrations that call outside services

A sales operations team wants a won opportunity to trigger a call to an external quoting or billing service. That call needs an API key. If the key is typed directly into a formula script, a workflow step or a request header, it sits in plain view for anyone who can open that automation, and it travels with every export or copy of the rule. An *App Secret* is an EspoCRM setting that holds a credential under a name, so the automation refers to the name instead of the value. The first decision is which external services your automations will call, because each one needs its own secret and its own owner.

Teams usually need App Secrets in three places: formula scripts that prepare or check data before a record is saved, workflows and BPM processes that call an outside service as one step, and Send HTTP Request actions that pass the key in a header. The formula reference at EspoCRM formula documentation lists where formula scripts run, and those are the places where a hardcoded key is most likely to appear. Before you build, decide who may edit each workflow, since editing rights determine who can see how a secret is used, even when they cannot see its value.

This page walks through creating a secret, reading it from formula, and referencing it in a Send HTTP Request header, then covers the checks to run afterward. Confirm the exact menu path, field labels and version behavior in your own EspoCRM instance before you rely on them, including whether an administrator can view a secret's value after saving it. Also confirm which of your automations write request details to logs, because a key that is hidden in a rule can still appear in a log or an error message.

Where API keys usually leak in a CRM build

Credentials rarely leak through one dramatic mistake. They spread through the everyday shortcuts of a CRM build: a value typed into a script, a header pasted into an action, a field left visible. Each place below is one a reviewer can check before the build reaches production.

Hard-coded values in before-save scripts

A Formula before-save script that calls an external service often carries the key as a literal string. Anyone who can edit the Entity Manager script, or who exports the metadata, can read it. Check every script in the entity's before-save and API before-save definitions for string literals that look like tokens, and confirm each external call reads its key from an App Secret instead.

Pasted values in workflow and BPM actions

Send HTTP Request actions in workflows and BPM processes are easy to configure by typing a header value directly into the action. That value is then stored in the workflow definition, where administrators who never handle the integration can see it. Review each action that sends an Authorization or custom key header and confirm the value is a reference to a secret, not the credential itself.

Credentials in user-visible fields

Teams sometimes store an integration key in a custom text field on Account or Settings-style records so that a script can read it later. Any role with read access to that entity, including portal or team-wide roles, can then see the value on the detail view or in a list export. Check each custom field's type and the roles that can view it, and move any credential-like field into App Secrets.

Exports, imports and copied records

A CSV export of a record or a report can include a field that holds a secret, and the file then travels by email or into a shared drive. Import files prepared by hand can carry keys in the same way. Before enabling exports for a role, confirm that no credential-bearing field is in the export column set, and treat any file that once contained a key as exposed.

Logs, debug output and screenshots

Debugging a failing integration often means logging the request or the script output, and a logged Authorization header is a live credential in a log file. Screenshots of a workflow configuration for a ticket or a training deck can show a pasted key in plain view. Check the server log location and retention, remove debug statements from production scripts, and review screenshots before they leave the team.

Shared administrator accounts and version control

When several people share an admin login, every secret they can read is effectively shared and nobody can be traced for a change. Exported configuration committed to a Git repository for review can also carry values that were typed into scripts or actions. Confirm that each admin has a named account, that repository exports are scanned for secret patterns, and that secrets are rotated after anyone with access leaves the project.

Which credential pattern fits each integration

Use App Secrets when EspoCRM itself must call a third-party service, such as a Send HTTP Request step in a workflow or a formula that reads a key before calling out. The key lives in EspoCRM's own store, so the formula and workflow reference a name instead of a literal value. Your CRM administrators own rotation: they update the secret in the administration area and test the workflow afterward, because nothing else in the stack changes.

Best fit: outbound calls made by a single EspoCRM workflow or before-save script.
Who rotates: the EspoCRM administrator, manually, with a test run after each change.
Trade-off: the value sits inside the CRM database, so anyone with administrative access to the instance can reach it.
Limit: the secret is only useful to EspoCRM formula and workflow logic, not to other systems.
Ask your team: who holds administrator rights today, and is that list reviewed regularly?

Before relying on this pattern, confirm which roles can view or edit secrets in your version and document the rotation steps.

How to create an App Secret and use it in formula and HTTP requests

This sequence moves an external API key out of formula text and workflow definitions and into an EspoCRM App Secret. The result is a workflow that sends authenticated HTTP requests while the key value stays in one managed location. Menu names and function syntax vary by version, so confirm each one in your instance before you build.

Locate App Secrets in your version
An administrator signs in and opens the administration area to find the App Secrets page. Menu names and their location can change between EspoCRM releases, so confirm the exact path in your instance before you start, and note it in your build record. Check: the list page opens and you can see any existing secrets. Record who holds administrator access, because that account can read the secret configuration.
Create the secret with a non-production value
Create a new App Secret with a name that describes the external system and its purpose, such as billing_api_key (illustrative). Enter a key issued for a sandbox or test account at the external service, not a production credential. Check: the record saves, and you confirm whether the value is displayed again after saving in your version. Keep the name stable, because workflows will refer to it.
Reference the secret in a formula script
Open the Formula Script in the workflow or BPM step that needs the key. Call the documented function that reads an App Secret by name, passing only the secret name, and assign the result to a variable. The formula documentation at EspoCRM formula docs lists the function and its syntax for your release. Check: the formula text contains the secret name and no key characters, and a test run produces the value in the variable without writing it to any field.
Add the secret to a Send HTTP Request header
In the workflow, add a Send HTTP Request action with a URL that points to your sandbox endpoint. Create the authorization header and set its value to the variable or secret reference that your version supports, confirming the exact syntax in your release notes or documentation. Workflows are an Advanced Pack feature. Check: the saved header shows a reference rather than a literal key, and the action passes validation without an error.
Test the call against a non-production endpoint
Trigger the workflow on a test record in a non-production instance. Review the sandbox service's request log to confirm it received the call and accepted the header. Then review the EspoCRM log files for the test key value. Check: the external service records an authenticated request, and the EspoCRM logs contain no copy of the key. If the key appears in any log, stop and adjust the logging before going further.
Confirm the key stays out of definitions and exports
Export the workflow definition and the relevant configuration from the test instance, then search the output for the test key value. Confirm your backup and migration process copies the secret store under its own controls rather than through workflow exports. Check: the search returns no matches, and the written procedure states how to rotate the value by updating the App Secret alone, without editing the workflow.

How an App Secret travels from storage to an outbound request

An App Secret is read on the EspoCRM server at the moment a workflow or formula runs, and its value is attached to the outgoing request as an HTTP header by a Send HTTP Request step. The sequence starts with a trigger such as a record save, a workflow step or a BPM task. The formula script executes in PHP on the server, looks up the secret by its name, and passes the value into the request headers. The request then leaves the server directly to the external service. Because the secret is resolved at execution time, rotating it in storage takes effect on the next run without editing the workflow. Workflows and BPM are part of the Advanced Pack, which the EspoCRM pricing page lists as included in all cloud plans. Self-hosted teams should confirm the same licensing position for their edition.

The browser and the user-facing record never need the secret. The value is not a field on the entity, so it does not appear in record detail views, list views, layouts or the client-side code that renders them. Users who only edit or view a record see the outcome of the call, such as a status field written by the workflow, and never the credential that produced it. Before go-live, test this in your own instance: open a record as a standard user, inspect the browser's network responses for that record, and confirm the secret value appears nowhere in them. Also confirm that the secret is not echoed in workflow logs or error messages in your version, because logs are often readable by a wider group than the people who manage the secret.

Access control matters most at the admin level. Anyone who can edit workflows or formulas can usually point a request at a different host and send the secret to it, and admins may be able to view or change stored secret values. Confirm in the EspoCRM security documentation and your own testing how your version exposes secrets to administrators. Keep the number of people who can edit workflows that use secrets small, review changes to those workflows, and avoid running daily work through admin accounts, as the security guidance recommends. Plan a rotation procedure with an owner, a schedule and a check that the next scheduled run succeeds after the change.

Security and operating controls around app secrets

App secrets keep credentials out of formulas and workflows, but the secret is only as safe as the people who can read or change it. The controls below limit who can touch integration credentials, how changes are reviewed, and where those credentials can be sent.

Restrict admin roles to integration maintainers

Only the people who maintain integrations should hold roles that can create, read or edit App Secrets and workflows that call external services. Review the admin role assignments on the EspoCRM side and confirm that sales and service users cannot open the Entity Manager or the workflow editor. Record who holds each role so that access reviews have a named list to check against.

Separate admin work from daily use

The EspoCRM security docs advise against using admin accounts for daily work. Maintainers should sign in with a regular user account for sales and service tasks and use a dedicated admin account only when changing secrets or workflows. This keeps an admin session from being exposed during routine browsing and makes admin activity easier to tell apart in the logs.

Plan rotation with the external provider

Rotating a key in EspoCRM is only half the job. Agree with the external provider how the old key is revoked, how the new key is issued, and who is responsible for each step. Update the App Secret and test the affected workflow before the old key is removed, and keep a dated record of each rotation so that a leaked or retired key can be traced.

Log and review workflow changes

Any change to a workflow that reads a secret or sends an HTTP request should go through a review step. Ask your partner or internal team to confirm that changes are recorded, that someone other than the author reviews them, and that the reviewer checks which secret is used and where the request is sent. Treat an unexpected change to a secret reference as a security event until it is explained.

Limit outbound destinations

A workflow that holds a credential can send it to any address its HTTP request points at. Restrict each Send HTTP Request step to the approved provider hosts and document them in the workflow description. Confirm with your network team whether the EspoCRM server can reach other destinations, and block outbound traffic that the integration does not need.

Test in a non-production instance first

Build and test new secrets and workflows in a separate EspoCRM instance that uses sandbox credentials from the provider. Confirm that the workflow reads the expected secret, that headers are sent correctly, and that failed calls produce a visible error. Only then copy the configuration to production, using production credentials that were never used in testing.

Questions teams ask before storing API keys in EspoCRM

Does the open-source edition of EspoCRM support App Secrets?

Confirm this in the documentation for the exact version you plan to run before you design around it. EspoCRM is licensed under AGPL-3.0 and the open-source edition can be downloaded and self-hosted for free, but the supplied material does not establish which features each edition includes. Check the release notes and documentation for your version, then test App Secrets on a staging instance built from the same package. If the feature is limited in your edition, decide on a fallback before the build starts, because changing how credentials are stored later means reworking every formula and workflow that reads them.

How much effort does an App Secrets setup take?

Effort depends mostly on how many external services EspoCRM calls and how many workflows, processes and formulas call them, not on the secret mechanism itself. The main drivers are the number of integrations, the header format each API expects, the number of environments such as test and production, and how many failure paths you need to verify. One-time work covers the inventory, design, configuration and testing. Recurring work comes from each new integration, which adds a secret, a test and a review. Ask any quote to list every integration, its endpoints, its environments and the processes that use it, because those items set the scope.

What does our internal team need to provide?

Your team needs to supply the inputs that only your organization holds:

Can our own team set up App Secrets without a partner?

Yes, if your administrators already know EspoCRM's formula language, workflow or BPM configuration and HTTP request settings, and they can test changes in a non-production instance. A partner adds value when the design needs review, when several integrations share credentials, or when failure handling must be tested before go-live. DeployOpen works on fixed scope agreed in writing before work starts, so you can ask for only the parts you cannot cover internally, such as the design review or the test plan. Whichever route you choose, the EspoCRM security documentation is a useful baseline for admin account practice.

How do we rotate API keys stored in EspoCRM?

Rotation is an ongoing process your organization owns, and the EspoCRM configuration does not replace it. A typical cycle creates a new key at the provider, updates the secret in EspoCRM, runs a test workflow or process, and then revokes the old key. Where the provider allows two active keys at once, keep both active during the switch so scheduled jobs do not fail. Confirm in the documentation for your version whether a secret change applies immediately, and whether secret values can appear in logs or audit records. Assign an owner and a review date to each key so rotation does not depend on memory.

What changes when we move from Advanced Pack workflows to BPM?

Both Workflows and Business Process Management come from the Advanced Pack, which is included in all EspoCRM Cloud plans, so the choice is about process design rather than licensing. Workflows are rule-driven automations, while BPM is a BPMN 2.0 process engine, so a single process can hold several steps and states across time. Formula Script is used in both, so a secret read through a formula follows the same pattern in each. Still, test every path in the process, including waits, retries and error branches, because the failure behavior differs. Check the formula documentation and the Advanced Pack page for the details that apply to your version.

Is it safe to put API keys directly into formula scripts?

No. A literal key in a formula script is readable by anyone who can edit that script, and it can be copied into exports, backups and screenshots taken during troubleshooting. Keep keys out of formula text and workflow definitions, and reference them by name instead. Limit who can edit scripts and workflows, treat those editors as privileged users, and avoid using admin accounts for daily work. Review existing scripts for hard-coded values before you migrate them to secrets, because a key already pasted into one script will remain valid until you rotate it.

Limits to confirm in your EspoCRM environment

App Secrets depend on the EspoCRM version, the extensions you run and how the instance is backed up and moved. Each card below is a check to run in your own environment before you rely on secrets in formula or workflow steps.

Feature availability in your version

Confirm that App Secrets, reading them in Formula Script and using them in Send HTTP Request headers all exist in the exact EspoCRM build you run. The current major line is 10.0.x, but the release notes only tell you which version shipped a change, so test each step on a staging instance at the version you will deploy. Record the version number in your design document so later upgrades can be checked against it.

Advanced Pack dependency for workflow steps

Check whether the workflow or BPM steps you plan to use require the Advanced Pack. Formula that runs in before-save scripts or API hooks may behave differently from formula inside a workflow action, so build a test for each execution point. Confirm the license tier you are buying covers the pack, since the pricing page includes it in all cloud plans and self-hosted editions may differ.

Formula function names in the installed build

Look up the exact function names for reading secrets in the Formula documentation for your installed version, then call each one from a test record and log the result. Do not assume a name from an older article or a forum post, because a misspelled or renamed function can fail silently in a workflow. Keep the verified names in your runbook next to the version they were tested on.

Secret handling in backups and migrations

Find out whether secret values are included in a database backup, an export, or a move to new servers, and whether they stay encrypted at rest. A restored instance may need the secrets re-entered, or it may carry plaintext values into a backup copy that more people can read. Write down who can take backups, where they are stored, and the restore steps that reissue or reset each credential.

Authentication pattern accepted by the external service

Confirm that the target API accepts the header style you plan to send, such as a bearer token, a custom API key header or basic credentials, and that it accepts the token lifetime and rotation schedule you need. Some services require signed requests or IP restrictions that a plain header cannot meet. Test with a sandbox key first and check the vendor's error responses for expired or revoked credentials.

How DeployOpen works on this

DeployOpen plans and implements self-hosted EspoCRM inside your own infrastructure, including how integration credentials are stored, referenced and rotated. We scope the secret inventory, build the formula and workflow references, and hand over documentation your team can run after go-live.

How we scope

We inventory every outbound integration that needs a key, token or password before any build starts.
Scope names which workflows, formulas and Send HTTP Request actions will read each App Secret.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work begins.

How we build

We create App Secrets with names that match each integration and keep raw values out of formulas and layouts.
Send HTTP Request headers are wired to secrets, and each call is tested against a non-production endpoint.
We check that workflow and BPM logs do not expose secret values during test runs.

How we hand over

You receive a register of secret names, owners, the workflows that use them and the rotation steps.
Admins are shown how to update a secret value without editing formulas or workflow definitions.
Access to the EspoCRM admin area that can view or change secrets is documented against your role model.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Retained support can cover rotating credentials on a schedule your security team sets.
We can re-test secret handling after EspoCRM upgrades or when a new integration is added.

Storing API keys in EspoCRM app secrets