Backend Integration

This guide covers the server side of the evaluated path. The developer overview links the browser, server, and policy guides in order. The maintained server sample is below.

Trust boundary

The browser passes a returned device identifier to your backend. The backend calls the authenticated device lookup with a server-held credential. The browser must never receive the credential, an Authorization header, or a secret environment variable.

The public v1 device route rejects an unauthenticated request. Evaluation access and an appropriately scoped credential are required before the lookup can return a tenant-scoped record.

A protected-action requestId is redeemed the same way, from the backend with a server credential; see Protected actions.

Handle transport before risk

Your server must preserve these outcomes:

• Received: a response contains the fields your evaluated policy requires.
• Missing: no record is present for that identifier in the current tenant and retention window.
• Invalid: a response exists but lacks fields required by your policy.
• Rate limited: the service rejected request frequency; follow the supplied operational guidance.
• Unavailable: authentication, authorization, network, or service failure prevented a usable read.

Only a complete received record belongs in a numeric comparison. Missing, invalid, rate-limited, and unavailable states are not score zero and are not low risk.

Maintained server sample

Send the device identifier to your backend, then call the authenticated v1 route with a server-held key. Replace every synthetic value with credentials and identifiers issued for your evaluation. An automated test checks these samples against fixtures kept with the documentation.

Read the device on your server

export async function lookupDevice({ deviceId, apiKey, fetchImpl = fetch }) {
  const response = await fetchImpl(
    `https://collect.noxtica.com/v1/device/${encodeURIComponent(deviceId)}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );

  if (response.status === 404) return { state: 'missing' };
  if (response.status === 429) return { state: 'rate_limited' };
  if (!response.ok) return { state: 'unavailable' };

  return { state: 'received', record: await response.json() };
}

Keep result states separate

The function below applies the rule above. A record counts as complete when it carries a numeric score and confidence; every other outcome keeps its own state.

export function classifyLookup(result) {
  if (!result || result.state === 'unavailable') return { state: 'unavailable' };
  if (result.state === 'rate_limited') return { state: 'rate_limited' };
  if (result.state === 'missing') return { state: 'missing' };

  const record = result.record;
  if (!record || typeof record.score !== 'number' || typeof record.confidence !== 'number') {
    return { state: 'invalid' };
  }

  return {
    state: 'received',
    score: record.score,
    riskLevel: record.riskLevel,
    confidence: record.confidence,
  };
}

Customer policy

Combine the lookup with the protected operation and the account, authentication, transaction, and abuse context your application already owns. Begin in observation mode. Compare the proposed action with confirmed outcomes before adding step-up or deny behavior.

Set an application deadline and choose a fallback for each protected surface. A successful API response does not prove that one threshold is appropriate for every route.

Verification checklist

• The credential remains in the server secret store.
• Browser requests carry only the lookup identifier and customer-owned business input.
• Received, missing, invalid, rate-limited, and unavailable paths are exercised.
• Logs omit credentials and unnecessary identifiers.
• Policy changes have an owner, observation evidence, and rollback path.

Run the maintained server sample and then trace the complete Integration Flow.