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 executions or its data.

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

Each application is one environment or the other, and its secret only works for its own. There is no flag on the request that switches between them: you hold two applications and two secrets.

The engine catalogue is environment-aware: List Engines on a sandbox application returns the sandbox engines, and only those.

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": "12345678Z",
    "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