Tool authentication

Most real tools need a credential. Omnia splits that into two halves on purpose:

	Field	What it is
Declaration	`httpSecurityOptions`	What kind of credential, and how it is sent. Returned by the API.
Value	`authTokens`	The secret itself. Encrypted at rest, never returned.

Keeping them apart means you can inspect a tool’s auth setup without exposing the secret, and rotate the secret without touching the shape.

Declaring

{
  "httpSecurityOptions": {
    "options": [
      { "requirements": { "bookingKey": { "headerApiKey": { "name": "X-Api-Key" } } } }
    ]
  },
  "authTokens": { "bookingKey": "sk_live_abc123" }
}

Each requirement declares exactly one of three shapes:

{ "bookingKey": { "headerApiKey": { "name": "X-Api-Key" } } }

{ "bookingKey": { "queryApiKey": { "name": "api_key" } } }

{ "bookingKey": { "httpAuth": { "scheme": "Bearer" } } }

`options` are alternatives

The list is acceptable alternatives — satisfying any one entry is enough. That is how you say “either an API key or a bearer token”:

{
  "options": [
    { "requirements": { "apiKey":      { "headerApiKey": { "name": "X-Api-Key" } } } },
    { "requirements": { "bearerToken": { "httpAuth":     { "scheme": "Bearer" } } } }
  ]
}

You may then fill only one of them. options must have at least one entry.

The typo guard

Every key in authTokens must be declared in httpSecurityOptions.options[].requirements. Otherwise:

{ "authTokens": { "bookngKey": "sk_live_abc123" } }

{
  "error": {
    "message": "authTokens key \"bookngKey\" is not declared in httpSecurityOptions.options[].requirements. Either declare the credential or remove the value.",
    "code": "BAD_REQUEST"
  }
}

Without that check the typo would save happily, never satisfy the real bookingKey requirement, and surface weeks later as an unexplained 401 from your own endpoint — with nothing in the logs naming which credential was missing. The reverse is not enforced: declaring two alternatives and filling one is intentional.

Inspecting

Values are never returned. A GET shows which slots are filled:

{
  "httpSecurityOptions": { "options": [ /* … */ ] },
  "setCredentials": { "bookingKey": true, "backupKey": false }
}

setCredentials exists so a UI can render •••••••• for a filled slot and an empty field for an unfilled one, without ever handling the secret.

Rotating

Send only the new value. Zero downtime — the change takes effect on the next call.

curl -X PATCH "https://api.omnia-voice.com/api/v1/agent-tools/TOOL_ID" \
  -H "X-API-Key: $OMNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "authTokens": { "bookingKey": "sk_live_NEW" } }'

Clear every slot with "authTokens": null. The same null-clears behaviour applies to agentReaction, httpSecurityOptions, and timeout.

How values are handled

Credentials are encrypted at rest, decrypted only while a single call’s payload is being assembled, and redacted from logging. They are never included in an API response.

Client tools cannot carry credentials — they run in the browser, where the user can read anything the page can. If a secret is involved, it must be an HTTP tool.

Get started

Core concepts

Tools

Telephony

Apps & SDKs

Guides

Examples

Speech to text

Help

Declaring

`options` are alternatives

The typo guard

Inspecting

Rotating

How values are handled

​Declaring

​options are alternatives

​The typo guard

​Inspecting

​Rotating

​How values are handled

Declaring

`options` are alternatives

The typo guard

Inspecting

Rotating

How values are handled