Skip to main content
Use an SDK key in a trusted server environment. For an application distributed to users, keep the SDK key on your backend and issue short-lived JSON Web Tokens (JWTs) to authenticated clients. This page describes core SDK 0.24.0 and Python aic-sdk 3.2.0. Check your binding in the compatibility matrix. The released browser package @ai-coustics/aic-sdk-wasm 0.23.0 uses core SDK 0.23.0 and exposes JWT refresh through processor.getProcessorContext().updateBearerToken(token). Follow the WebAssembly guide for its browser setup; the Python methods below belong to the native binding.

Server-side authentication

Get an SDK license

Create an SDK key on the developer platform. Store it in your deployment’s secret manager and inject it as AIC_SDK_LICENSE at runtime. Pass the complete value to the processor as shown in the SDK quickstart. Do not commit the key, print it in logs or put it in a browser bundle, URL or client-accessible configuration. If a key is exposed, replace it through the developer platform and redeploy affected services. Self-service keys use online authorization and usage reporting. Local inference does not imply disconnected operation. See network and telemetry behavior before restricting network access.

Client-side authentication

Your backend authenticates users and issues short-lived tokens while keeping the SDK key private. Protect the token endpoint with authentication, rate limits and HTTPS.
JWT credentials and in-place token updates were introduced in core SDK 0.19.0, available in Python from 2.3.0. Refresh requires both the initial credential and its replacement to be JWTs.

Mint a token on your backend

The platform’s signed SDK key has a base64-encoded JSON payload containing an api_key field. The token endpoint uses that inner key as the HTTP Basic username, with an empty password. This decoding step belongs only on your backend. It does not verify the SDK key’s signature. Save this as token_service.py in your backend project. It uses the Python standard library and expects AIC_SDK_LICENSE in the environment.
Run python token_service.py. A successful request prints an expiry timestamp without logging the token. Your authenticated application endpoint can return the function’s result to the authorized client. Set Cache-Control: no-store on that response and exclude response bodies from request logs. A failed request raises an HTTP or connection error. Check the key and backend connectivity before retrying. Do not retry authentication failures indefinitely or forward raw upstream error bodies to clients.

Initialize the SDK with the token

The following native Python example demonstrates the credential argument. Install aic-sdk==3.2.0 in an isolated environment and supply a fresh token as AIC_SESSION_TOKEN. Your application normally obtains that token through its authenticated backend API.
Verify activation by processing audio with the quickstart and checking session errors. Keep model downloads and network requests outside the audio callback.

Refresh before the token expires

Use the returned expiry or the JWT’s exp claim to schedule refresh. Do not assume a fixed lifetime. Request a replacement early enough to allow for clock skew and transient network failures, for example 5 minutes before expiry for a token whose lifetime exceeds that margin. After your authenticated backend returns a fresh token, update the existing processor context:
The update preserves processor state and does not reload the model. Run retrieval and refresh from your control thread, with one refresh in flight per session. Use bounded retries with backoff and jitter for transient failures, stop retries at shutdown and surface a failed refresh to your application. TokenUnsupportedError means the original credential or its replacement is not a JWT. The previous credential remains in use. A processor created with an SDK key must be recreated to switch to JWT authentication.

Handle expired or rejected credentials

Do not depend on one exception to identify every authentication failure: JWT activation, authorization or required usage-reporting failures can stop processing. Tolerated network failures do not establish offline access.
In Python, Processor.process() raises on disallowed processing and returns no output array. Choose a failure policy: stop the session, report degraded operation or use an approved fallback. Do not label bypassed audio as enhanced.
See troubleshooting for recovery steps and deployment for startup, readiness and shutdown checks.