Authentication for Noesis

Noesis uses your DetectifAI API keys. A key must be allowed to use Noesis:

Choose the permissions when you create a key under API keys in the dashboard. A key without them gets 403 with insufficient_scope.

#HTTP requests

Send the key as a bearer token:

curl https://api.noesis.detectif.ai/v1/detect/usage \
  -H "Authorization: Bearer $DETECTIF_API_KEY"

#The WebSocket

Send the same header on the WebSocket upgrade request:

import os

import websockets

async def open_stream():
    return await websockets.connect(
        "wss://api.noesis.detectif.ai/v1/detect/stream?encoding=mulaw&sample_rate=8000",
        additional_headers={"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}"},
    )

import WebSocket from "ws";

const ws = new WebSocket("wss://api.noesis.detectif.ai/v1/detect/stream?encoding=mulaw&sample_rate=8000", {
  headers: { Authorization: `Bearer ${process.env.DETECTIF_API_KEY}` },
});

#Stream tokens

Some clients cannot set headers on a WebSocket: Twilio <Stream>, a browser, or a telephony provider where you only enter a URL. For these, your server creates a stream token for each call and the client passes it instead of the key:

• In the URL: wss://api.noesis.detectif.ai/v1/detect/stream?token=ntk_...
• On Twilio: <Parameter name="token" value="ntk_..."/> inside <Stream>. See Twilio.

curl -X POST https://api.noesis.detectif.ai/v1/detect/stream-tokens \
  -H "Authorization: Bearer $DETECTIF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"record": true}'

import os

import requests

resp = requests.post(
    "https://api.noesis.detectif.ai/v1/detect/stream-tokens",
    headers={"Authorization": f"Bearer {os.environ['DETECTIF_API_KEY']}"},
    json={"record": True},
    timeout=10,
)
token = resp.json()["token"]

const res = await fetch("https://api.noesis.detectif.ai/v1/detect/stream-tokens", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.DETECTIF_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ record: true }),
});
const { token } = await res.json();

• A token opens one call. It expires 5 minutes after it is created if it has not been used.
• It belongs to the key and account that created it, and carries the key's Noesis permission.
• record (optional, default true) sets whether the call is recorded. See Data and recording.
• Create tokens on your server, right before the call. Never create them in browser or app code, because that needs the API key.

#Keep keys out of URLs

Never put an API key in a URL. A request with ?api_key= is refused with api_key_in_url; rotate a key that was sent that way. Never put an API key in browser or mobile app code: give those clients a stream token from your server.

#When a key or token is refused

See Errors.