Skip to main content
Your action endpoint decides who’s allowed to call it. OpenCX gives you three ways to reach that decision — pick one or combine them.

​
The Three Paths

​
Global Variables

Store once, OpenCX injects the value into every action call for your organization. Values are encrypted at rest and decrypted per request.
1

Open the variables page

Go to Settings → Variables.
2

Add a variable

Set a key and value. The key becomes the HTTP header name on every outbound action call.
3

Reference from an action

Nothing further to wire up — any action whose endpoint sits behind that header will authenticate.
Use a full Authorization header value (e.g. Bearer <token>) when your API expects Bearer auth — OpenCX sends the value verbatim, it does not prepend Bearer .

​
Widget Headers

Pass per-user credentials from your frontend at widget-init time. OpenCX uses them only for that contact’s action calls and does not persist them.
Widget headers override same-named global variables for that contact’s session. Use this when each signed-in customer needs their own scoped token.

​
Context Headers

When your org has context headers enabled, OpenCX adds four identifying headers to every action call: Your API can use these to:
  • Trace an action call back to a specific conversation in the OpenCX inbox — the session ID is a clickable link.
  • Rate-limit per org without customers passing their own org ID as a parameter.
  • Scope responses — e.g. return a contact’s orders based on x-opencx-external-user-id instead of trusting a query parameter the AI extracted.
Context headers are opt-in at the org level. If you need them on, ask support to enable automatic action headers for your org.
Every action call also carries User-Agent: OpenCX so your firewall and logs can filter.

​
Choosing A Path

​
Security Best Practices

Treat x-opencx-org-id as a signal, not a credential — pair it with a global-variable shared secret your API also checks. That way a leaked URL alone can’t forge OpenCX traffic.
Redact anything matching Authorization, *-Token, *-Key in your access logs. OpenCX does not replay headers, but your own log pipeline and dashboards can.
OpenCX refuses to call http:// URLs. If your endpoint isn’t behind TLS today, put it behind a gateway that is.
Update the global variable value — no action edit needed. Existing in-flight tool calls finish against the old value; the next call uses the new one.

Build An Action

Form fields, headers, parameters, test.

Execution

How headers reach your API at call time.

Troubleshooting

401s, 403s, and signal-header gotchas.

Widget Authentication

Full widget auth model including identity verification.