Getting Started

What is ScamSafe?

ScamSafe is a scam-resilience assessment from the Global Cyber Alliance (GCA). A learner answers a short, structured self-assessment, gets a score for how well they recognize, avoid and recover from scams, and leaves with recommendations and a step-by-step plan to improve. An AI tutor answers questions along the way.

Scoring is deterministic: the same answers always produce the same scores and recommendations. The tutor explains and guides, but never decides a score.

Administrators run the deployment from a separate admin panel, where they manage the questions, recommendations, tutor content and branding, and monitor usage.

Audiences

A learner is assessed as one of five audiences. The audience decides which questions are asked and which scale they are scored on.

Audience	learnerType	Scale
Individual	individual	Individual (0 to 3)
Young adult	youngAdult	Individual (0 to 3)
Senior	senior	Individual (0 to 3)
Small business	smb	Organizational (0 to 5)
Nonprofit	nonprofit	Organizational (0 to 5)

The assessment

1. Scoping: unscored yes/no questions about the learner's situation. They decide which later questions apply, so nobody is asked about something they don't use.
2. Knowledge and tools: scored questions for every audience.
3. Organizational preparedness: scored questions for small businesses and nonprofits only.

Before starting, a learner can optionally say what brought them to ScamSafe. If they do, their results lead with what they asked about. If they have just been scammed, recovery comes first. Skipping it changes nothing.

Scores

Every scored question belongs to a category, such as account takeover or payment scams, and every category rolls up into one of four groups:

Group	What it measures
Recognize scams	Spotting a scam for what it is, wherever it arrives
Verify before you act	Checking a request is genuine before responding to it
Protect accounts and money	The safeguards in place before anything goes wrong
Respond and recover	Knowing what to do, and who to tell, once something has happened

Results lead with the four group scores, and each one expands into the categories beneath it. Scoring explains exactly how they are calculated. Scores are shown on the audience's scale with a maturity level:

Scale	Levels
Individual (0 to 3)	None, Basic, Intermediate, Advanced
Organizational (0 to 5)	Based on NIST CSF: None, Initial, Repeatable, Defined, Managed, Optimizing

Recommendations and roadmaps

Every category scoring below 70% gets a recommendation, as long as the recommendation catalog has an entry for it: the GCA courses, toolkit guides and other resources that address it, weakest category first. A learner who scores 70% or above everywhere gets a general set of resources for their audience instead.

From a completed assessment, a learner can build a roadmap: a plan of concrete steps drawn from their recommendations, grouped like their results. They work through it at their own pace, earn badges as they go, and confirm their progress by retaking the scored part of the assessment.

The tutor

The tutor is an AI assistant that answers questions about scams and the learner's own results. It sees the learner's scores and roadmap so it can tailor its answers, but it can't change them. Where a deployment has no AI provider configured, or its license has lapsed, the tutor is unavailable and the rest of ScamSafe keeps working.

Hosting your own deployment

Partners can run ScamSafe on their own infrastructure, under their own branding.

• Deploying ScamSafe: configuration, sign-in, backups and first start.
• Licensing: the license key a partner deployment needs, and what happens if it lapses.
• Admin guide: running the deployment from the admin panel.

Using the API

The REST API is served under /api/. The OpenAPI spec is at /api/docs.yaml (or /api/docs.json), and the API reference on this site renders it.

Authentication

Sign-in is through single sign-on (OIDC), and accounts are invite-only:

1. POST /api/auth/login/start returns the identity provider's sign-in URL.
2. The identity provider sends the user back to the app, which posts the result to POST /api/auth/callback.
3. The response sets the scamsafe_session cookie, which authenticates every later request.

There are no API keys.

Key endpoints

POST /api/assessment/start                   Start or resume the caller's assessment; returns the scoping questions
POST /api/assessment/answer                  Submit one answer
POST /api/assessment/batch-answer            Submit several answers at once
GET  /api/assessment/{sessionID}/results     Scores, maturity, strengths, weak areas and recommendations
POST /api/assessment/{sessionID}/complete    Mark the assessment complete
POST /api/chat                               Ask the tutor a question
GET  /api/recommendations                    The full recommendation catalog
GET  /api/roadmap                            The caller's roadmap
GET  /api/feature-status                     Which optional features are available on this deployment

Admin routes require the admin role. They cover users and invites, the question bank, recommendations, tutor content, branding, usage and alerts. See the API reference for the complete list.