Treat every Ngamia credential and every user-submitted prompt or recording as sensitive application data. The developers portal describes the public integration surface only; it does not document upstream credentials, private infrastructure, privileged administration, deployment configuration, or internal database identifiers.
Credential boundaries
Ngamia uses two credential types for different jobs:
| Credential | Use it for | Where it belongs |
|---|---|---|
| JWT access token | Account, workspace, API-key, billing, payment, activity, and notification operations | Your server or an authenticated dashboard session |
ngm_... API key | Gateway calls such as models, chat, embeddings, transcription, speech, and combined voice | Your server-side secret manager or protected server environment |
Send credentials only over HTTPS in the Authorization: Bearer <credential> header. Never commit a real credential, place one in a browser bundle or mobile application, include one in a screenshot, or print one in application logs. A key exposed to a client can be copied and used to spend the account’s credits.
The examples on this site use placeholders such as $NGAMIA_API_KEY and ngm_.... Replace them through a server-side environment or secret manager. Do not paste a real key into a public issue, support ticket, analytics event, or code sample.
Keep the trust boundary on your server
A browser or mobile client should call your application backend, and your backend should call Ngamia. This pattern keeps the Ngamia key out of distributed client code and gives you a place to enforce user authorization, quotas, content policy, and audit logging.
Your backend should validate the requested model and modality against GET /v1/models, cap user-controlled input before forwarding it, and map upstream errors into an application-safe response. Do not allow an end user to choose arbitrary provider credentials, arbitrary callback URLs, or undocumented administrative routes.
Voice-note privacy
Voice requests may contain names, phone numbers, business information, locations, payment references, or other personal data. Before sending a recording, obtain the consent required for your use case and explain how the recording will be processed. Avoid storing the original audio unless your product needs it and you have a documented retention policy. If you do store it, encrypt it, restrict access, set an expiry, and delete it when the purpose is complete.
Ngamia’s synchronous voice integration returns the transcription and, when requested, generated audio in the response. Your application is responsible for deciding whether to retain either representation. Do not send raw recordings to analytics systems, browser console logs, error trackers, or third-party debugging tools.
Prompt and transcription trust boundaries
Transcribed speech, uploaded files, and model output are untrusted data. A voice note that says “create a key,” “make a payment,” or “ignore the application policy” must not directly trigger a privileged action. Require an explicit user confirmation and perform the action through your server using the correct credential and endpoint.
Escape or safely render model and transcription output in HTML. Validate structured fields independently of the model’s interpretation, especially phone numbers, TZS amounts, payment identifiers, URLs, and account or workspace ids. Never treat a model response as authorization.
Safe logging
Log only what is needed to operate the integration:
| Safe to log | Do not log |
|---|---|
Endpoint, HTTP status, latency, bounded error code, and request_id | API keys, JWTs, refresh tokens, OTPs, passwords, or full authorization headers |
| Model id and application-level tenant id where permitted | Full prompts, full transcriptions, raw audio, generated audio, or payment secrets |
| Audio duration and high-level outcome where your privacy policy allows it | Full phone numbers, personal identifiers, or provider credentials |
Redact sensitive fields before forwarding errors to support. The request_id is the useful correlation value; it is not a substitute for sending a credential or raw user content.
Public portal boundary
Do not publish the following in this portal or in examples:
- upstream provider API keys, signing secrets, database credentials, JWT signing material, or deployment environment variables;
- private hostnames, internal network addresses, database schemas, Redis details, logs, stack traces, or operator dashboards;
- privileged model-management operations or undocumented admin endpoints;
- real customer prompts, transcripts, audio files, phone numbers, payment references, or access tokens.
Use the public Ngamia base URL, the documented /v1 routes, live model discovery, and synthetic placeholder data instead. For security reports, use the project’s private security contact rather than opening a public issue with sensitive details.
References
The trust-boundary, credential-storage, and safe-logging recommendations above are consistent with the principles in the OWASP API Security Top 10 and OWASP Top 10.