Obelisk · The Obelisk API

Start here

Everything an app or agent needs to use Obelisk is discoverable from a single request — no HTML scraping, no guesswork.

The manifest: GET /api?format=json returns this entire contract as machine-readable JSON (this page is its human twin).
Standards auth: OpenID Connect discovery + JWKS. Use authorization-code + PKCE to obtain tokens.
JSON where it carries a contract: account, organization, API-manifest, and changelog surfaces negotiate JSON; static editorial pages remain HTML and are listed here for discovery.
Guides: Obelisk for agents · Integrate Obelisk · Works with your database.

Base URL https://obeliskgate.com · Version obelisk-api-1

Authentication

Each endpoint declares one of four auth levels — a small closed vocabulary you can branch on:

Level	What it means
none	public
session	obelisk_session cookie OR body.token
bearer	OIDC access token (Authorization: Bearer)
owner	session + org owner/admin

Bearer tokens are OIDC access tokens presented as Authorization: Bearer <token>. Session auth accepts the HttpOnly obelisk_session cookie (browser) or a token in the JSON body (server-to-server).

Discovery

Well-known entry points for clients and agents:

What	URL
`openid_configuration`	`/.well-known/openid-configuration`
`jwks`	`/.well-known/jwks.json`
`manifest`	`/api`
`agent_interface`	`/.well-known/obelisk-agent`
`saml_idp_metadata`	`/saml/idp/metadata`
`health`	`/healthz`
`transparency`	`/.well-known/obelisk-transparency.json`
`security_txt`	`/.well-known/security.txt`
`changelog`	`/changelog?format=json`

release_history

Public-safe product history for humans and agents, bound to the revision serving it when deploy metadata is available.

Method	Endpoint	Auth	What it does
GET	`/changelog`	none	Human release history (HTML; versioned JSON with ?format=json or Accept: application/json).

Authentication & OIDC

Passkey-first sign-in + OIDC.

Method	Endpoint	Auth	What it does
GET	`/auth`	none	The immersive sign-in/sign-up experience (HTML).
GET	`/auth/assertion-options`	none	Begin a (usernameless) passkey sign-in. query — user: optional account name
POST	`/auth/assertion-verify`	none	Complete a passkey sign-in; returns the session + where to go (home). body — user: optional; response: WebAuthn assertion; deviceId: optional
POST	`/auth/verify-session`	none	Server-to-server: validate a session token; returns { ok, identityId }. body — token: macaroon
GET	`/auth/userinfo`	bearer	OIDC userinfo for an access token.
POST	`/auth/magic/request`	none	Request an email magic-link (where enabled). body — email: string; dryRun: session-gated: return the link, don't send

Account

The universal Obelisk account — one identity across every app.

Method	Endpoint	Auth	What it does
GET	`/account`	session	Your account page (HTML; JSON with ?format=json → the full profile).
GET	`/account/export`	session	Download a portable, secret-free copy of your account (JSON).
POST	`/auth/profile`	session	Set your display name. body — displayName: string
POST	`/auth/account/rename`	session	Change your username (old name stays a resolvable alias). body — newUsername: string
POST	`/auth/preferences`	session	Merge your preferences (theme/lang/contrast/motion/text/email). body — preferences: object
POST	`/auth/passkeys/list`	session	List your passkeys (no public keys).
POST	`/auth/passkeys/rename`	session	Rename a passkey. body — credId: string; label: string
POST	`/auth/passkeys/remove`	session	Remove a passkey (never the last one). body — credId: string
POST	`/auth/passkeys/add-options`	session	Begin adding a passkey to your account.
POST	`/auth/passkeys/add-verify`	session	Finish adding a passkey. body — response: WebAuthn attestation
POST	`/auth/totp/setup`	session	Begin TOTP setup (pending) → { secret, uri, qrSvg }.
POST	`/auth/totp/confirm`	session	Confirm + activate TOTP with a code. body — code: 6 digits
POST	`/auth/totp/disable`	session	Turn off TOTP.
POST	`/auth/recovery/regenerate`	session	Generate new backup codes (shown once).
POST	`/auth/sessions/revoke`	session	Revoke a session. body — identifier: string
POST	`/auth/devices/revoke`	session	Sign out a whole device — revokes every session it holds, then drops it from the device ledger. body — deviceId: string
POST	`/auth/signout`	session	Clear the session cookie.

Organizations

Method	Endpoint	Auth	What it does
POST	`/auth/orgs/create`	session	Create an organization (you become owner). body — name: string; website: optional url
GET	`/org/:slug`	session	Org dashboard (HTML; JSON with ?format=json), member-gated.
POST	`/org/:slug/scan`	owner	Run an external security-posture scan → an Obelisk Rating for the website. body — website: optional override
POST	`/org/:slug/invite`	owner	Create a role-scoped invite link. body — role: member\|admin; email: optional
POST	`/org/:slug/invite/revoke`	owner	Revoke an invite. body — code: string
GET	`/join/:code`	none	Accept an invite (signs you in first if needed).

Per-project profile

The on-top layer: each project's own per-user profile slice, scoped to its OIDC client.

Method	Endpoint	Auth	What it does
GET	`/api/project-profile`	bearer	Read this project's profile slice for the token's user → { sub, project, profile }.
POST	`/api/project-profile`	bearer	Shallow-merge into this project's slice. body — profile: object

SAML federation (Obelisk as your IdP)

Obelisk as the SAML 2.0 IdP for downstream platforms (GitHub, Slack, AWS, …).

Method	Endpoint	Auth	What it does
GET	`/saml/idp/metadata`	none	IdP metadata: entity ID, SSO URL, and the pinned X.509 signing certificate — hand this URL to any SAML service provider.
GET	`/saml/idp/sso`	none	SAML sign-on endpoint: authenticates passkey-first, then auto-POSTs an RSA-SHA256-signed assertion to the SP's ACS. query — SAMLRequest: SP AuthnRequest (redirect binding)

The verified seal

The verified “Secured by Obelisk Gate” seal + per-site verification pages.

Method	Endpoint	Auth	What it does
GET	`/embed/seal.js`	none	Drop-in loader: one script tag renders the live seal card on a relying party's page.
GET	`/embed/v1/seal`	none	The framed seal card itself (rendered live from obeliskgate.com; can't be forged).
GET	`/verify/:rp`	none	Public verification page for a relying party — anyone can confirm the seal is genuine.

Website scan

The public website posture scan (the same engine behind the org Rating).

Method	Endpoint	Auth	What it does
POST	`/api/scan`	none	Scan a public https:// website's security posture → a rating with concrete levers. SSRF-guarded, throttled per client. body — url: public https:// website (domains only)

Contact

Reach the team.

Method	Endpoint	Auth	What it does
POST	`/api/contact`	none	Send a message to the team (form-encoded: name, email, subject, message). Honeypot-protected, throttled. body — name: string; email: string; subject: string?; message: string

Content negotiation & errors

Selected account, organization, API-manifest, and changelog surfaces return JSON with ?format=json or Accept: application/json; static editorial pages remain HTML.

Failures share one shape — { ok:false, reason:<code>, message?:<human> } on failures; HTTP status mirrors it. — and the HTTP status mirrors it, so a client can branch on either.

The machine-readable contract

This whole reference is generated from one manifest. Fetch it as JSON and an agent can discover and use every surface without reading a line of HTML:

curl -s https://obeliskgate.com/api?format=json

Building an agent? Start with Obelisk for agents, then the per-project profile contract. Questions → Help Center.