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

PathUse it forWhere it lives
Global variablesCredentials every customer shares — a server-to-server API key, a signing secretSettings → Variables
Widget headersCredentials that differ per customer — a session token, a per-user JWTYour frontend, passed to the widget at init
Context headersIdentifying the OpenCX-side session / org / contact to your APIAttached automatically by OpenCX

​
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. 
const options = {
  token: 'YOUR_COPILOT_TOKEN',
  headers: {
    Authorization: `Bearer ${userJwt}`,
  },
};
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:
HeaderValue
x-opencx-org-idYour organization UUID
x-opencx-session-idThe conversation session UUID — the trace key
x-opencx-ticket-numberNumeric ticket ID for the session
x-opencx-external-user-idThe contact’s external ID if they’re authenticated
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

SituationPath
Every customer hits the same backend with the same server-to-server keyGlobal variable
Each signed-in customer has their own scoped tokenWidget header (with a global variable for any shared service-account header)
Your API needs to know which OpenCX session / org / contact made the callContext headers

​
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.