Hosted API Reference (API Docs)

An API Docs application turns an OpenAPI document into a hosted API reference. You push the document; AuthAction serves it, either to anyone with the link or only to people who sign in through your tenant’s hosted login.

It is useful when a reference should not be public — a partner API, an internal platform API, a beta — and you would rather not build a login in front of a static docs site.

How it works

You push the document; AuthAction never fetches it. The dashboard loads it in your browser (from a URL your machine can reach, or a file) and stores it with the application, or you push it from CI with the Management API. A spec that only exists on an internal host still works.
Each reference is its own application. It is a public client with no API server attached, so publishing documentation never depends on registering the API it describes.
A private reference uses your existing login. Readers sign in through the connections you enable on the application — enable only your enterprise connection and the reference is readable by your staff alone.
It is served from AuthAction’s own origin. The reference renderer is not loaded from a third-party CDN, so readers’ IP addresses are not sent anywhere else.

The reference renders your document for reading. It does not obtain tokens for readers to call your API from the page.

Create an API Docs application

In the dashboard, open Applications → API Docs.
Click Create API Documentation and give it a name. Nothing else is required.

Publish a document

On the application’s Reference tab:

Either enter a URL and click Load from URL, or click Upload file. The URL is fetched by your browser — if the host blocks cross-origin requests, download the file and upload it instead.
Check the summary (title, version, number of endpoints).
Click Publish document.

The document must be JSON, with an openapi (OpenAPI 3) or swagger (Swagger 2) version field and a paths object. Documents up to 5 MB are accepted.

Publishing again replaces the previous document.

Publish from CI

The document is a field on the application, so any pipeline that can call the Management API can publish it. Use an M2M application with access to the AuthAction Management API:

# 1. Token for the Management API
TOKEN=$(curl -s -X POST https://acme.eu.authaction.com/oauth2/m2m/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_M2M_CLIENT_ID",
    "client_secret": "YOUR_M2M_CLIENT_SECRET",
    "audience": "https://acme.eu.authaction.com"
  }' | jq -r .access_token)

# 2. Publish the document
jq -n --slurpfile spec openapi.json '{docsSpecDocument: $spec[0]}' |
  curl -X PATCH "https://acme.eu.authaction.com/api/v1/applications/APPLICATION_ID" \
    -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    --data @-

APPLICATION_ID is the id shown in the API Docs application’s header. Send "docsSpecDocument": null to unpublish.

Where it is served

As soon as a document is published, the reference is available at:

https://{tenant-name}--docs.{region}.authaction.com/{client-id}

For example, https://acme--docs.eu.authaction.com/m4WZQFVVv72hTyvLZsX6fI7E2TXZAhl6. Each tenant’s references share that host, told apart by client id. The link is shown on the Reference tab, and Open Reference in the application header opens it.

The docs host is deliberately separate from acme.eu.authaction.com, the host that holds your users’ login session — customer-supplied content is never rendered on the origin that holds session cookies.

On your own domain

To serve a reference at, for example, https://docs.acme.com:

Open Tenant Settings → Custom Domain and add the domain.
For Serves, choose API reference, then select the API Docs application.
Create a CNAME from the domain to your tenant hostname (acme.eu.authaction.com) and verify it, exactly as for a login domain.

A domain serves one reference, at its root. The sign-in callback for a private reference is registered for the domain automatically when it is verified, and removed when the domain is.

Public or private

On the Reference tab, set Visibility:

Visibility	Who can read it
Public	Anyone with the link
Private	Anyone who can sign in through the connections enabled on the application

For a private reference, the Connections tab decides who can read it. Enable only an enterprise connection (Okta, Entra ID, Google Workspace) and the reader must be in that directory. Enable a password or social connection that allows sign-up, and anyone who registers can read it.

When an unauthenticated reader opens a private reference, they are sent to your hosted login, then back to the reference. The document itself (openapi.json) is withheld from them too. A sign-in lasts 12 hours.

Activity

The Activity tab records when a document was published and when a custom domain was connected or disconnected — the two things to check when a reference does not load.