What stops being done by hand when your awareness program has an API

On the first business day of every month, someone on your team logs into the awareness platform, downloads a file, pastes it into a spreadsheet and builds the slide the board is going to see. Then they repeat the operation with the other tools in the stack. The work is careful and the number that reaches the top is correct. It happens once a month because doing it costs an entire morning.

That effort is not explained by missing data. The data is there, every platform holds it and shows it on its own dashboard. What is missing is the door it can leave through without anyone keying it in.

I lead the engineering team at SMARTFENSE, and in technical conversations with customers that door almost never shows up as a request for an API. It shows up as the monthly report without the morning of work, the account that gets created on its own when a new person joins, the evidence ready the day the auditor calls. The platform API is what sits underneath all three requests.

What does it mean for an awareness program to have an API?

The API of a security awareness platform is the interface that lets another system read and modify the program’s data without going through the screen. Where a person logs in and clicks, a program makes a call and gets the same data back as JSON.

Put that way it sounds like an implementation detail, but four design decisions change quite a lot for whoever has to consume it.

It is REST over mandatory HTTPS, the design any systems team already knows how to consume without training. It returns JSON, so the result lands straight in a BI tool with no transformation layer in between. Responses are paginated, which matters once the directory holds twenty thousand people and a single query cannot bring them all back at once. And dates travel in UTC using ISO 8601, which is what lets you compare a campaign in Mexico against one in Spain without arguing about what time each of them started.

None of the four is exotic. They are what makes the integration something the customer’s own systems team finishes, instead of a project with our team on the other side.

Which data leaves the program, and where does it go?

There are five data areas available, and they are best read by what they solve rather than by what they are called.

Campaign and awareness activity results are the input for the report, what today leaves as a downloaded file. Risk scoring is the score per person, group and organization that the platform already calculates and displays as a heat map in its reports. User and organization management is the directory, with joiners, leavers and the structure of business units. Auditing and traceability is the activity log, the one the auditor asks for. And content is the inventory of what is published and assigned.

Those five areas usually head toward three systems the organization already runs. The BI tool, where program data sits next to every other indicator instead of living on a separate dashboard. The SIEM or the GRC, which add per-person risk to the telemetry they already process. And the evidence repository, which stops being filled with screenshots.

The direction is worth flagging, because this is where two different conversations get mixed up. When I wrote about building the human risk score with SIEM signals, the flow ran inward, telemetry feeding the calculation. Here the flow runs outward, program results heading toward the organization’s systems. They are two separate integrations, and they are contracted and authorized separately.

Which tasks stop depending on a person?

These are the five that come up first when a customer connects the API, ordered by how often we get asked for them.

1. The recurring report. Data travels on its own into the BI tool and the report refreshes without anyone assembling it. That is the month-end morning you get back, and also what makes it viable to bring three concrete answers to the board the day the board asks for them, rather than the day the calendar says so.
2. Joiners and leavers. The HR system pushes the change and the program’s directory reflects it. Whoever joins gets their training from day one and whoever leaves stops having it assigned, without anyone remembering to do it.
3. Compliance evidence. Instead of reconstructing by hand who completed what and when, the evidence repository is fed from the source. That is the mechanism behind a compliance dashboard that updates in real time rather than a quarterly snapshot.
4. Risk score inside the security dashboard. Per-person scoring reaches the SIEM or the GRC and gets correlated with every other signal, without the security team having to open another tool to look it up.
5. Consolidation across organizations. When the program is spread across several organizations, each with its own administration, the API is what lets you read the whole set without going in one by one.

The pattern behind all five is the same. The platform keeps doing what it did, and what changes is who triggers it. Each one is a task that today has an owner, a calendar and a risk of being forgotten, and that starts running on its own.

How do you authorize an integration without opening the platform too much?

Connecting two systems is the easy part. Whether that connection is safe comes down to three questions, and none of them requires reading the spec.

On whose behalf does the integration act? There are two modes. One is the automated process that runs overnight with nobody behind it and holds an identity of its own. The other is an application acting on behalf of a specific person and inheriting their permissions. Mixing them up gets expensive. An automated process running with a human administrator’s credentials turns that account into a shared one, and the day that person leaves the organization nobody knows what breaks when you deactivate it.

How much can it touch? OAuth 2.0, the standard authentication rests on, lets you narrow each integration down to a minimum permission, its scope. The system that builds the monthly report can be limited to reading results and never touch the people directory. It is the difference between handing over the whole filing cabinet and handing over one drawer. Being able to do it does not mean it gets done, because the convenient path is always to grant full permission and move on. Two of the ten main API security risks published by OWASP are, precisely, permission failures.

What gets logged? Every call from an integration is an action on your employees’ data. If the audit log does not let you reconstruct which system read what and when, you have access nobody can review afterward. Ask about it before signing.

When is the API the right answer, and when is what you already have enough?

This is the part a vendor tends to skip, and the one that saves the most time.

A good share of what a customer thinks needs coding is already solved in the integrations catalog and gets configured without writing code. Authentication is delegated to the identity provider through SAML 2.0, LDAP, Microsoft Entra ID, Google or Auth0, and the full flow is covered in how the SSO integration works end to end. Delivery through Slack or Microsoft Teams, sending training to Moodle, the connection with SAP SuccessFactors or with Vanta each have their own connector.

The API comes in where the catalog does not reach, and that is almost always whatever is specific to each organization: your BI tool, your internal onboarding workflow, your GRC, cross-referencing results with a field that only exists in your systems.

The rule of thumb I use in those conversations is simple. If the system on the other side is a known market product, look for the connector first. If the system on the other side is yours, that is where the API comes in. And in both cases the connection happens between servers, with nothing deployed on each employee’s device, which is why we integrate via API and not with an agent.

Frequently asked questions

What is the API of a security awareness platform?
It is the interface that lets another system read and modify the program’s data without going through the screen. Where a person logs in and clicks, a program makes a call and gets the same data back as JSON.

What can you automate with a security awareness program API?
The recurring report feeding a BI tool, joiner and leaver provisioning from the HR system, compliance evidence collection, sending each person’s risk score to the SIEM or the GRC, and consolidating results when the program is spread across several organizations.

Do I need the API to connect the program to my identity provider?
No. Authentication is handled by the catalog connectors, such as SAML 2.0, LDAP, Microsoft Entra ID, Google or Auth0, which are configured without writing code. The API is for what no connector covers, like your in-house BI tool or your own onboarding workflow.

How do you authorize an API integration without granting too much access?
With OAuth 2.0 and scope-based access. The scope narrows what each integration can read or write, so the system that builds the monthly report can be limited to reading results without touching the user directory.

What is the difference between integrating via API and installing an agent?
The API connects to the organization’s systems server to server, with nothing to deploy or maintain on each employee’s device. There is no component to patch on the endpoint and no new surface to administer.

If you are working out how to connect the program to what you already run, the API documentation and the connector catalog are public. Starting there usually saves the meeting where everyone discovers the connector already existed.