Inside the empowsec Developer Docs: Your API Launchpad

Most integration projects do not stall on code - they stall in a support queue. A developer wants to know which endpoint lists users, what scope a key needs, or what a 429 response means, and instead of reading the answer they open a ticket and wait. empowsec ships its developer documentation as a portal built directly into the product at /docs, so the answer to almost every integration question is one bookmark away, for resellers and companies alike.

We covered what the empowsec API and webhooks can actually do in an earlier deep dive. This article is about the documentation experience itself: how the portal is organized, what each section covers, why the changelog deserves a place in your team's routine, and how a single role-aware link gets any admin to their API key without hunting through menus.

A Documentation Portal Built Into the Product

The portal lives at /docs on your empowsec instance and needs no login to read - a developer can evaluate the integration surface before an account even exists. There is no PDF to version and no external wiki to drift out of date; the docs ship with the product and are localized like the rest of the platform, so your team reads them in the same language as the application itself.

The left-hand navigation is organized into three sections that mirror how teams actually integrate. The Reseller API section serves MSPs and partners automating a client portfolio. The Company API section serves in-house IT and security teams connecting a single organization. And the Resources section collects everything both audiences share: webhooks, error handling, and the changelog. Whatever your role, the path from question to answer follows the same shape - pick your section, follow the guides in order, then keep the reference pages open while you build.

The Reseller API Section: Automate a Client Portfolio

The reseller track opens with an overview and a getting-started guide, then an authentication page, before fanning out into four reference areas: Companies, Seats, Users, and Reports. Together they map exactly to the operations an MSP performs every week. The Companies reference covers managing the client organizations you serve. The Seats reference documents reading your pool summary and adjusting a client's seat allocation - the programmatic twin of the seat pool workflow in the reseller portal. The Users reference covers managing people across client companies, and the Reports reference is where cross-client usage data comes from.

Because reference pages spell out methods, paths, and required scopes, an integrator can see at a glance that reading seat data and writing seat allocations are separately scoped operations - and provision credentials accordingly. That is the difference between documentation that describes an API and documentation that teaches you to use it safely.

The Company API Section: Connect One Organization

The company track follows the same rhythm - overview, getting started, authentication - and then narrows to the three things an in-house team most often wires up: Users, Training, and Phishing. The Users pages cover programmatic user management, which is the foundation for keeping empowsec in sync with your HR system of record. The Training pages document how to pull security awareness training data, so completion status can flow into compliance dashboards without manual exports. The Phishing pages cover phishing simulation data, letting security teams fold simulation outcomes into the same reporting pipeline as their other risk signals.

Keeping the company track separate from the reseller track is a deliberate choice. A company integrator never has to read around portfolio-management concepts that do not apply to them, and an MSP developer never has to guess which endpoints operate across clients versus within one. Each audience gets a linear path: read three guide pages, then build against the references that match your use case.

Resources: Webhooks, Errors, and the Changelog as Your Upgrade Radar

The Resources section is shared infrastructure for both audiences. The Webhooks page documents empowsec's push side - how event payloads reach your endpoint so integrations can react to what happens instead of polling for it. The Errors page catalogs response codes and their meanings, which is what turns a failing integration from a mystery into a diagnosis: is this an authentication problem, a malformed request, or something on the server side? Building error handling against a documented catalog is far more robust than guessing from one observed failure.

The Changelog deserves special attention as a working habit, not just a page. Every documented change to the API lands there, which makes it your upgrade radar: a periodic skim tells you when new capabilities appear that could simplify an existing integration, and when upcoming changes deserve a closer look before your next deployment. Teams that review the changelog on a schedule are never surprised by their integration's behavior; teams that do not, learn about changes from their monitoring instead.

One Link to Your API Key, Whatever Your Role

Documentation traditionally struggles with one instruction: 'now get your API key'. The right key page differs by audience, so docs either describe every path and confuse everyone, or describe one path and strand the rest. empowsec solves this with a role-aware deep link: /docs/get-api-key. A signed-in Reseller Admin who follows it lands directly on the reseller API key management page. A Company Admin lands on the company API settings. Someone who is not signed in is sent to the login page first, and a signed-in user whose role has no API access is returned to the docs with a clear notice that API keys are managed by admins.

It is a small feature with outsized effect: every tutorial, onboarding email, and internal runbook can contain one universal link, and each reader ends up exactly where their role allows. No screenshots of menus that look different per role, and no support tickets that begin with 'where do I find my key?'.

Key Takeaways

• The docs portal lives in the product at /docs: no PDFs, no stale wiki, localized like the rest of the platform, readable without a login.
• Three sections mirror real integration paths: Reseller API (Companies, Seats, Users, Reports), Company API (Users, Training, Phishing), and shared Resources.
• Guides run in order - overview, getting started, authentication - so a new integrator has a linear path from zero to first request.
• The Errors page turns failures into diagnoses, and the Webhooks page documents the push side of the platform.
• The Changelog is your upgrade radar: review it on a schedule to catch new capabilities and assess changes before they reach your integration.
• /docs/get-api-key is role-aware: reseller admins, company admins, visitors, and non-admin users each land exactly where they should.