VikingCloud: documenting your security API as you build it

How a leading cybersecurity AI company built their first general audience API at the same time as their developer portal.

There’s a ‘documentation divide’ intrinsic to API innovation: a gap between building APIs and keeping their docs up to date. This story is about that: about a valiant cybersecurity provider, VikingCloud, whose developers wisely chose to mind-that-gap before even writing a line of JSON:

We started using Redocly before we even had the API fully developed. The turnkey solution from Redocly made it incredibly simple to get up and running.

- Jon

Let’s learn about their experience from Jon Marler, the company’s Product Admiral. Give it up for Jon, and see you all in Valhalla! ⚔️

The continuous monitoring SaaS for cyber threats.

  • Dublin, Ireland and Chicago, IL
  • Cybersecurity platform
  • 1 billion security events processed daily
  • Developer Portal with BitBucket CI for their first customer-facing API
Jon Marler

Product Admiral

Background: building docs while building API

We were able to release a developer portal on the same day as our GA API release. That was a big win in our book.

- Jon

VikingCloud is a cyber defense SaaS that makes protection against cyber threats proactive and continuous. They specialize in network infrastructure, compliance, and assurance testing and assessments.

VikingCloud’s flagship product is the Asgard Platform™, an AI-based tool that continuously monitors cyber threats and collects security alerts in real time, processing more than a billion security events a day.

To-build list: Asgard API 1.0

Jon’s team was tasked with creating an API to complement the Asgard Platform’s powerful dashboard and workflows. And to make sure customers would use it, they needed better developer onboarding than what the security industry is all too accustomed to:

We wanted to offer an automation API to our customers, but wanted to avoid the obvious issues with creating a super technical PDF describing how to use it.

- Jon

These kinds of PDFs are expensive to put together, and they have to be updated with every change, no matter how small. That’s why our vikings knew they’d have to dynamically document their API from day one, and educate their customers in a simpler and more timely fashion.


  • mark
    100% OpenAPI spec
  • mark
    Docs rendered automatically
  • mark
    Docs auto-update when API changed
  • mark
    Turnkey developer portal solution
  • mark
    Bonus props: one source control to rule 'em all

Auto-docs from OpenAPI

To build their API, Jon and team settled on the most popular specification, OpenAPI (OAS). And ease of documentation, turns out, was one of the decisive advantages:

When we decided to use OpenAPI to build our customer facing API, it really opened so many doors. I learned we could build our documentation automatically from the API specification.

- Jon

Jon got down to researching methodologies and products, and amongst the tools that could render OAS into API docs automatically, one stood out: Yours Truly, Redocly.

OAS into docs, easy as cake 🎉

Docs-like-code from day minus-one

Building and documenting APIs at the same time is an approach known as docs-like-code, and it’s our design philosophy and point of pride here at Redocly. By making this strategic choice, the VikingCloud team kept their whole API pipeline in one place and saved a bunch of very limited developer time.

“Turnkey” developer portal

Redocly’s architecture is unique in that it uses the API registry as a single source of truth, which leverages the standardized format of API definitions to render fully functional developer portals out of the box – what Jon calls a “turnkey solution.”

Being built directly from the API definition — which, if you’re doing things right, changes often — the portal is always up to date. And it’s easy to get a v1 out and kicking with portal templates.

We love how easy it is to work with and even the portal builds are easy. The amount of time it has saved us with our developer portal is immense!

- Jon

BitBucket CI pipeline

The engineers building the Asgard API also love using Redocly in their day to day. They connected Redocly builds to their CI pipeline with a native BitBucket integration, so they can publish straight to Redocly with every production update.

We love how easily we could integrate Redocly with our development workflow. Our software engineers only need to go to one place to keep API documentation and API implementation in sync while keeping it all under the control of our automated CI/CD pipeline.
Rav Tonsiengsom

VP of Engineering at VikingCloud

Here’s how their pipeline looks like day in, day out:

Code-first API building approach

Push API and docs to BitBucket

OAS 3.0 definition updated in Registry

Developer portal auto-updates

Build developer hubs as you build your APIs

The plot thickens: acquisition & rebrand

To make matters more interesting – at least to you, dear reader – VikingCloud’s first foray into public APIs happened in the middle of a major acquisition. Jon and the Web Risk Monitoring service were part of SecureTrust, a company that VikingCloud acquired in 2020.

Acquisitions usually imply months of migrations, code refactoring, and a code-spaghetti of Zoom meetings. But when it came to their API developer hub, Jon and team were all settled:

When we were acquired, it was also one less thing that we would have to tear down and rebuild as it was already hosted externally. All we had to do was update the branding, and we were good to go.

- Odin

Namely, Redocly makes it easy to change your developer portal theme, and style individual elements as you see fit with just a few lines of code. And just like that, the before becomes the “after” in the blink of an eye:


How VikingCloud is using Redocly

Developer Portal

Asgard Platform developer portal

Custom-designed developer hub launched in record time from API definitions.

Secure multi-auth

BitBucket CI with Workflows

One CI pipeline to push API docs to prod with every update to the API definition.


API Reference docs

For Asgard core services and Web Risk Monitoring (WRM) APIs, neatly integrated with the portal.

Making security easy to document

Our mission at Redocly is to accelerate API ubiquity — and no matter how simple the use case, or early the stage of production, static PDFs are not the way to get there.

Our friends at VikingCloud were forward-looking enough to understand that documentation and developer onboarding should be a key decision factor in your API journey. By embracing docs-like-code from day zero, they bypassed the struggles encountered by some of our customers:

  • Some use in-house documentation tools until they become unwieldy to maintain (see Australia Post or Checkr)
  • Others use less flexible third-party API docs tools from the start, then switch to Redocly to expand their feature set (see Brex) or to launch more customized developer experience (for example, Sinch)

Building your first API can be a daunting task, but if you start with a documentation pipeline firmly in place, a big part of the job is done, dusted, and off your to-build checklist. So, kudos to our Vikings — and see you in Valhalla!

Superpower your API lifecycle with Redocly