Skip to main content

Quick Start Guide

Get up and running with Trusted Accounts in under 5 minutes. Start with server-side integration (required), then optionally add the frontend SDK for stronger detection.

Step 1: Get Your Credentials​

  1. Visit the Developer Console
  2. Sign up for a free account
  3. Create your first project
  4. Copy your SECRET_KEY and PUBLISHABLE_KEY from project settings

You need the secret key for server-side integration and the publishable key later if you add the browser SDK or hosted challenge pages.

Step 2: Server-side Integration (Required)​

Call POST /api/v1/check-request from your server on every page request. Start in observe mode: always serve the page (fail-open on timeout) while decisions appear in your dashboard.

// Call on every page request from your server
const API = 'https://api.atmosvere.eu/api/v1/check-request';
// Visitor IP from the incoming request (use your framework/proxy headers)
const ip = req.ip || req.headers['x-forwarded-for'] || '';
// Path the visitor requested (e.g. /pricing?ref=ads)
const requestedPath = req.originalUrl || '/';
// Session/visitor ID from the trusted_id cookie (empty on first visit until the API sets the cookie)
const trustedId = req.cookies?.trusted_id ?? '';
// (optional) Request headers for stronger detection — exclude authorization, cookie, etc.
const headers = {
  'user-agent': req.headers['user-agent'] ?? '',
  referer: req.headers.referer ?? '',
};
// (optional) Cookie names only, never values (e.g. ['trusted_id'])
const cookies = req.cookies ? Object.keys(req.cookies) : [];

// Send these fields to Atmosvere in the POST body
const payload = { ip, requestedPath, trustedId };
// (optional) include headers and cookies when available
if (Object.keys(headers).length) payload.headers = headers;
if (cookies.length) payload.cookies = cookies;

// Default to allow if the API is slow or unreachable (fail-open)
let checkResponse = { decision: 'allow' };
try {
  // Fail-safe timeout: abort slow API calls so you still serve the page (fail-open)
  const controller = new AbortController();
  setTimeout(() => controller.abort(), 400);
  const apiRes = await fetch(API, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.SECRET_KEY}`,
    },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });
  // Forward Set-Cookie so the visitor receives trusted_id from the API
  const setCookie = apiRes.headers.get('set-cookie');
  if (setCookie) res.setHeader('Set-Cookie', setCookie);
  checkResponse = await apiRes.json();
} catch (_) {
  // Timeout or error: keep default allow (fail-open)
}

// OBSERVE MODE (default): always continue — decisions show in your dashboard
next();

Step 3: View Your Results​

  1. Open your Developer Console
  2. Go to Home → Live traffic to see server checks appear in real time
  3. Open Bot Protection for protection metrics and blocked/challenged requests — aggregated dashboard data can take up to 24 hours to appear after your first checks

For stronger browser-side signals, add this script to your HTML <head>:

<script
  async
  src="https://sdk.atmosvere.eu/js-sdk.js"
  onload="new TrustedTraffic({publishableKey:'YOUR_PUBLISHABLE_KEY'}).init()">
</script>

This step is optional but recommended. The SDK observes traffic in the browser and improves detection quality. See Frontend Integration for details.

Advanced: Enforce Decisions​

When you are ready to block or challenge visitors (not just observe), handle the API response:

DecisionAction
allowContinue to the requested page
challengeRedirect to the hosted challenge page
blockRedirect to the hosted blocked page

Full examples with redirect URLs: Step 2: Activate active protection

For edge deployment (e.g. Cloudflare Workers), see CDN integration.