API Access, Authentication and Required Headers

Every API integration starts with three questions: how do I reach the API, who is allowed to call it, and what must I send with every request? Capacity Private Cloud answers the second differently from most hosted APIs. The platform does not authenticate callers itself. It runs inside your Kubernetes cluster and relies on your network and cluster controls, and it uses a small set of identifiers, sent as headers or message fields, to tell tenants apart, audit activity, and match requests to responses. This article explains each of these, how to reach each API, and what the errors usually mean, so you can get a first call working and secure it properly.

The APIs at a glance

API	Protocol	Used for	Where the identifiers go
Speech API (`lumenvox.api`)	gRPC	ASR, transcription, TTS, CPA, and AMD	`deployment_id` and `operator_id` in the session create request and in global requests; `correlation_id` on any request
Speech Reporting API (`lumenvox.api.ReportingAPIService`)	gRPC	Usage and results reporting	Headers: `x-deployment-id`, `x-operator-id`, `x-scopes`
Management API	REST	Deployments, configuration, and keys	Headers on every request
Voice Biometrics API	REST	Voice biometrics enrollment and verification	Headers on every request
Biometric Reporting API	REST	Voice biometrics reports	Headers on every request

MRCP clients do not call these APIs directly. They connect to the MRCP API server, which sits outside the Kubernetes cluster and uses gRPC to reach the Speech API. See Supported Connection Protocols for how the protocols fit together, and API Overview for what each API offers.

Authentication and authorization

The platform does not provide user identification (authentication) or permission checking (authorization) for its APIs. The containers are designed to run inside a Kubernetes cluster, which has its own role-based access control, and you provide any further access control that your organization requires. Which mechanism you use is implementation specific.

The headers identify; they do not authenticate. Anyone who can reach an API and knows a deployment ID can send a request with it. Protect the APIs with network controls rather than relying on the headers.

The measures that protect an installation are the ones you would apply to any internal service:

Restrict network access. Secure cluster nodes and other services with appropriate firewalls and VPC configuration, and follow Kubernetes security best practices.
Restrict the sensitive routes at the ingress. With the Istio Gateway API ingress mode, global.lumenvox.ingress.internalAllowlist (a list of CIDRs) restricts access to the Admin Portal, Deployment Portal, file store, Management API, and Reporting API. With the default NGINX ingress, restrict these routes with a whitelist-source-range entry in httpAnnotations. See Helm Chart Changes in Version 8.0.0.
Keep the TLS certificate current. The ingress terminates HTTPS for the APIs using the speech-tls-secret certificate. See How to renew the speech-tls-secret certificate.
Add your own gateway if you need user-level access control. If your organization requires credentials such as tokens, enforce them in a gateway or proxy in front of the platform. The platform does not interpret them.

For the platform’s own security configuration, see Security Set Up Considerations.

Required identifiers

Three identifiers accompany every request, and a fourth is optional.

Identifier	Type	Purpose	Required
`x-deployment-id`	GUID	Identifies the tenant, or subscriber, that the request belongs to. It ring-fences data to that deployment and is used for licensing and usage tracking. The ID is assigned when the deployment is created.	Yes
`x-operator-id`	GUID	Identifies who or what made the call, for auditing. Your organization assigns it to each person or system that calls the APIs and keeps the mapping. The examples use `00000000-0000-0000-0000-000000000001`.	Yes
`x-scopes`	String	Declares the privileges the calling application requires to access a resource. The documented scope names are `VB` for the Voice Biometrics API, `MGMT` for the Management API, and `REPO` for the Reporting APIs. The Management API reference and the speech configuration example use all three together, `VB MGMT REPO`.	Yes, on the REST APIs and the Reporting API
`x-correlation-id`	GUID	A unique identifier for the call, so you can match requests and responses to transactions in your own system. If you omit it, the platform generates one.	No

Give each call its own correlation ID. You can repeat a GUID across different APIs, but not across calls to the same API that you want to tell apart.

Headers and message fields

The REST APIs and the Reporting API take the identifiers as HTTP or gRPC headers. The Speech API takes them as fields in the request messages; see ASR gRPC Integration for how deployment_id and operator_id are used in session_create.

Identifier	REST and Reporting API (header)	Speech API (message field)
`x-deployment-id`	Header on every request	`deployment_id` in `session_create` and in global requests
`x-operator-id`	Header on every request	`operator_id` in `session_create` and in global requests
`x-scopes`	Header on every request	No equivalent field
`x-correlation-id`	Optional header	`correlation_id`, optional on every request message

Reaching the APIs

From outside the cluster

Requests normally come in through the cluster’s ingress controller over HTTPS on port 443. Each externally exposed API has its own hostname, which is a name followed by the hostnameSuffix configured for your installation, for example management-api.example.com.

Hostname prefix	API
`lumenvox-api`	Speech API (gRPC)
`biometric-api`	Voice Biometrics API
`management-api`	Management API
`reporting-api`	Speech Reporting API (gRPC)
`reporting-bio-api`	Biometric Reporting API (REST)

If DNS is not configured for these names, the client needs hosts file entries that point to the cluster IP. See Setting Up a Deployment. The client must also trust the certificate the ingress presents.

For example, this grpcurl call retrieves a usage report through the ingress. Replace the identifiers and hostname with your own:

grpcurl \
  -H "x-deployment-id: <your-deployment-id>" \
  -H "x-operator-id: 00000000-0000-0000-0000-000000000001" \
  -H "x-scopes: REPO" \
  -d '{}' \
  reporting-api.example.com:443 \
  lumenvox.api.ReportingAPIService/UsageReport

See Licensing & Usage Reporting for the call and its output.

From inside the cluster

Services in the cluster can call the APIs directly by their service names, without the ingress. For example, the Management API is available inside the lumenvox namespace at management-api-service.lumenvox:5110. This is useful for air-gapped or restricted environments where the ingress is not reachable. This REST call reads the speech configuration:

curl -X GET \
  'http://management-api-service.lumenvox:5110/Management/ConfigurationSettings/SpeechConfiguration' \
  -H 'accept: application/json' \
  -H 'x-deployment-id: <your-deployment-id>' \
  -H 'x-operator-id: 00000000-0000-0000-0000-000000000001' \
  -H 'x-scopes: VB MGMT REPO'

See Configuring Speech Settings Using the Management API for the full procedure.

Deployments and tenants

A deployment is an individual tenant or subscriber on the platform. Data and configuration are kept separate per deployment, and licensing usage is tracked per deployment, which is why x-deployment-id is required on every request. A deployment is created with the Admin Portal or the Management API. When you create one, you can let the platform generate its ID or supply an existing one. See Creating a Deployment.

Errors from the REST APIs

The REST APIs return errors as a JSON object with the fields Error, ErrorCode, HttpStatusCode, HttpErrorCode, Message, and MessageData. The API specifications declare the HTTP status codes 400, 401, 403, 404, 409, and 500 for their operations. Read the Message first; it usually names the problem.

Troubleshooting

Symptom	Likely cause and fix
A REST call fails on the first attempt	Send all three headers, `x-deployment-id`, `x-operator-id`, and `x-scopes`, on every request, and make sure the two IDs are valid GUIDs.
A configuration or resource that should exist is not found	The `x-deployment-id` belongs to a different deployment. Data is ring-fenced per deployment, so check the ID.
A Management API call is rejected	Check that `x-scopes` includes the values the call needs. Use `MGMT` for the Management API. The speech configuration example documents all three values, `VB MGMT REPO`.
`session_create` fails	The session create request needs `deployment_id` and `operator_id`. Check that the deployment ID is a valid ID for your installation.
The Reporting API call fails	Send the three identifiers as headers, as in the usage report example, and use `x-scopes: REPO` for a usage report.
The API cannot be reached from outside the cluster	Check DNS or hosts entries for the API hostname, that the ingress allowlist includes your client address, and that the client trusts the ingress certificate.
Certificate errors	The certificate in `speech-tls-secret` may have expired or be missing a hostname. See the certificate renewal article.
You need to trace one call end to end	Send your own `x-correlation-id` (or `correlation_id`) and search for it in your logs and responses.

Was this article helpful?