Authentication & keys

Two different things are protected here, and they use different mechanisms. Your application proves who it is with a secret in a header. The end user’s credentials, which travel inside the request, can be encrypted with a public key so that not even an intercepted body reveals them.

The application secret

Every call carries it:

X-APP-SECRET: <your application secret>

Secrets are issued per application in the console, and an application can hold more than one. That is what makes rotation uneventful: mint the new secret, deploy it, then revoke the old one. Revoking a secret never touches the application, its sessions, its executions or its data. Security & keys is the screen.

When authentication fails, the answer is an HTTP status and a stable detail code — branch on the code, show your own message:

Sandbox and production

The application decides how far a run can reach; the engine you name decides where this one goes. There is no flag on the request: the engine is the switch.

So a sandbox application can never reach a real person, whatever it asks for, and a production one can still run the same rehearsal it was built on — to reproduce a case, or to check a release of your own against data that cannot hurt anyone. A rehearsal says so wherever it shows: the execution is flagged sandbox, and its session token starts with st_test_ instead of st_live_.

The engine catalogue follows the same rule, one environment per answer. List Engines lists your application’s environment unless you pass environment: a production application sends environment=sandbox to see the engines it can rehearse with, and a sandbox application that asks for production is refused with 403 production_not_enabled_for_this_app.

Base URLs

The explorer beside each endpoint in the reference lets you pick a server, so you can try a call without leaving this documentation.

Encrypting the credentials you send

Everything below is optional — the API accepts plain JSON over TLS — and it is worth doing anyway. TLS protects the connection; this protects the value, from the moment it leaves your process until it is used inside ours.

Each application has an RSA key pair whose private half is generated inside the platform and never leaves it. You get the public key. Encrypt with it and nobody downstream can read what you sent: not an intermediary, not a proxy log, not your own process afterwards.

That asymmetry is the whole point, and it is why this is the right envelope for somebody else’s password: a shared key would mean whoever can encrypt can also decrypt, and both sides holding the same secret is exactly what you do not want here.

{
  "parameters": {
    "username": "44444444A",
    "password": "rsa::Q2lwaGVydGV4dEJhc2U2NA=="
  }
}

{
  "parameters": "hybrid::QW5FbmNyeXB0ZWRKU09OT2JqZWN0"
}

The same envelope works for Resume an Execution — which is where one-time codes travel, and where it matters most.

A certificate renewal is not a key rotation

Worth knowing before it happens, because the words sound alarming and the event is not. Reissuing the certificate re-signs the same key pair: everything you have already encrypted still decrypts, and the certificate you installed keeps working until you choose to replace it. Generating a new pair is the destructive one — anything encrypted against the old public key becomes unreadable — which is why it is refused for an application that already has one.

Not storing the credentials at all

The most robust protection is not to hold the value. If your application has tokenization enabled, one execution can hand you a token that stands in for those credentials from then on — scoped to one engine, one customer and one set of features, revocable at any moment.

Every response carries