Pro App Secrets
Pro apps often need credentials — an API key, a client id and secret, a token for another system. Secrets let you store those credentials in the managed backend, where the app can use them but never see them.
A secret is write-only: you can set it and replace it, but nobody can read it back — not you, not the App Builder, and not the running app. The interface only ever shows the name, an optional description and a masked hint of the last characters.
When to use secrets
| Need | Use |
|---|---|
| A password or key for an external service | Secrets |
| Data the app creates and reads | Table storage |
| A document or reference list | File storage |
Secrets are never used on their own — they are referenced by a web request, which runs on the backend and attaches the credential there.
Enabling secrets
- Open the app in the App Builder.
- Switch to the Backend tab.
- Select Secrets from the left menu.
- Turn on the section.
Secrets require a Pro app, and only users with Design access to the app can manage them.
Adding a secret
Click Add secret, then give it:
- a name — starts with a letter, contains letters, digits and underscores, for example
ACME_CLIENT_SECRET; - an optional description — what the credential is for and where it came from;
- the value — stored encrypted immediately and never shown again.
To change a credential later, use Replace and type the new value. There is no way to reveal the old one.
Limits: up to 25 secret names per app, up to 4 KB per value.
Global values and per-instance values
Every secret name can hold two kinds of value:
- a global value, used by the app everywhere;
- an optional value for a specific ERP.net instance.
When the app makes a request, the backend resolves each secret automatically:
- If the app is running against a connected ERP.net instance and that instance has its own value — that value is used.
- Otherwise the global value is used.
- If neither exists, the request fails with a message naming the missing secret.
This lets one app serve many customers: the request definition stays the same, while each instance supplies its own account credentials.
Example — a delivery app calling a courier API:
ACME_CLIENT_ID
Global → the shared demo account
demo.my.erp.net → the customer's own account id
ACME_CLIENT_SECRET
Global → the shared demo account
demo.my.erp.net → the customer's own account secret
Run the app on demo.my.erp.net and it uses the customer's account; run it anywhere else and it falls back to the shared one.
What the App Builder can and cannot do
You can ask the App Builder to prepare the credentials an integration needs:
This app will call the Acme API. Declare the secrets it needs.
Which secrets does this app already have?
The App Builder can create secret names and tell you which ones are still empty, but it can never read or set a value — you enter values yourself in Backend → Secrets. It will say so and point you to the section.
How secrets stay safe
- Values are encrypted before they are stored and can only be decrypted by the backend while a request runs.
- Nothing in the browser, the app code, or the App Builder conversation ever receives a value.
- Test results and logs redact credentials and authorization headers.