All Endpoints

Every public endpoint of Nautilus on one page. All of them are served from a single host:

https://api.vernesoft.com

Use this page as a map: each row links to the reference section that documents the request body, the response schema, and the SDK equivalents. If you are integrating for the first time, start with Installation instead — the SDKs cover most of this surface without hand-written HTTP calls.

Authentication at a Glance

A key is vrn_ followed by random characters and carries a set of scopes, one per API, that you tick when you create it. A key is accepted only on the APIs it has the scope for — a key with only the relay scope on a Clockwork route is rejected with 403 Forbidden. Keys are created on the Dashboard → API Keys page and are scoped to a single tenant, so the tenant is always derived from the key rather than from the request. See API Keys.

SurfaceAuthHeader
/v1/gate/*API key with the gate scopeAuthorization: Bearer vrn_...
/v1/relay/*API key with the relay scopeAuthorization: Bearer vrn_...
/v1/clockwork/*API key with the clockwork scopeAuthorization: Bearer vrn_...
/v1/passepartout/*API key with the passepartout scopeAuthorization: Bearer vrn_...
/auth/*none — end-user self-service flows—
/public/*none—

Server-side only. API keys carry full engine access. Never ship one to a browser, a mobile app, or a WASM bundle.

Some Gate endpoints additionally require an end-user credential alongside the API key — the Kratos session token in an X-Session-Token header. Those rows are marked below.

Sign-in and users — Gate API

Full reference: Sign-in and users API reference.

Identity Management

MethodEndpointDescription
POST/v1/gate/identitiesCreate an end-user identity
GET/v1/gate/identities/{id}Fetch one identity
PATCH/v1/gate/identities/{id}Update an identity's traits
DELETE/v1/gate/identities/{id}Delete an identity permanently
PATCH/v1/gate/identities/{id}/stateActivate or deactivate an identity
POST/v1/gate/identities/{id}/resend-verificationRe-send the email verification message
GET/v1/gate/identities/{id}/metadataRead your custom metadata for an identity
PATCH/v1/gate/identities/{id}/metadataMerge custom metadata into an identity

Listing all identities is a Console operation, not an API-key one — the key surface addresses identities by id.

Sessions

Full reference: Session Management.

MethodEndpointDescription
GET/v1/gate/identities/{id}/sessionsList an identity's sessions (revoked ones too, active: false)
DELETE/v1/gate/identities/{id}/sessionsRevoke every session of one identity
DELETE/v1/gate/sessions/{session_id}Revoke a single session

Auth Flows

Self-service flows for your end-users. Each returns a Kratos flow object whose UI nodes your frontend renders. See Settings Flow for the full lifecycle.

MethodEndpointDescription
GET/v1/gate/auth/loginStart a login flow
GET/v1/gate/auth/registrationStart a registration flow — an API flow, completed by two POSTs to its ui.action; the answer carries session_token
GET/v1/gate/auth/recoveryStart an account recovery flow
POST/v1/gate/auth/recovery/submitSubmit a recovery code
GET/v1/gate/auth/verificationStart an email verification flow
POST/v1/gate/auth/verification/submitSubmit a verification code
GET/v1/gate/auth/settingsStart a settings flow — requires X-Session-Token
POST/v1/gate/auth/settings/submitSubmit a settings change — requires X-Session-Token
GET/v1/gate/auth/login?aal=aal2Start the second-factor step for a session — requires X-Session-Token
GET/v1/gate/auth/sessionWhether a session meets your tenant's requirements — requires X-Session-Token

Login is completed against the flow's own ui.action URL, which points back at the Kratos public routes under /auth/*: a plain POST of JSON, with no API key, cookie or CSRF token. The successful response carries session_token — that is the X-Session-Token value for the flows above. These are API flows, so none of them redirects and none reads an X-Return-To header. Social login is offered through the login flow.

A password submit finishes the login and returns a session at assurance level aal1. TOTP MFA is a second flow on top of it: GET /v1/gate/auth/login?aal=aal2 carrying that session, completed against its own ui.action.

Tenant Settings

MethodEndpointDescription
GET/v1/gate/settings/oidc-providersRead the social login providers enabled for your tenant
PUT/v1/gate/settings/oidc-providersReplace the enabled provider list
GET/v1/gate/settings/securityRead passwordless_enabled and mfa_enabled
PUT/v1/gate/settings/securityUpdate those security flags
GET/v1/gate/settings/webhooksList your Gate webhooks
POST/v1/gate/settings/webhooksRegister a webhook
PATCH/v1/gate/settings/webhooks/{id}Update a webhook
DELETE/v1/gate/settings/webhooks/{id}Delete a webhook

Organizations & Roles

Full reference: Organizations and Roles.

MethodEndpointDescription
POST GET/v1/gate/organizationsCreate an organization; list the project's organizations
GET PATCH DELETE/v1/gate/organizations/{org_id}Read, rename or delete an organization (its roles and memberships go with it)
POST GET/v1/gate/organizations/{org_id}/rolesDefine a role with its permissions; list the roles
GET PATCH DELETE/v1/gate/organizations/{org_id}/roles/{role_id}Read, change or delete a role (refused with 409 while someone holds it)
POST GET/v1/gate/organizations/{org_id}/membersGive an end user a role in the organization; list the members
PATCH DELETE/v1/gate/organizations/{org_id}/members/{identity_id}Change a member's role or deadline; remove them
GET/v1/gate/identities/{identity_id}/organizationsAn end user's organizations and roles, live — the complete list behind orgs_truncated

Audit Log

Full reference: Audit Log.

MethodEndpointDescription
GET/v1/gate/audit-logRead the account's audit log, newest first — filters action, actor_id, actor_type, target_id, from, to; cursor paging. Read-only

Tokens & Authorization

Full reference: Access Control.

MethodEndpointDescription
POST/v1/gate/tokensMint a scoped access token for an identity
POST/v1/gate/tokens/introspectValidate a token and read its claims
POST/v1/gate/authorizeAsk whether an end user may do something in an organization (resource: "organization:<id>", action a permission such as invoices:write), or is one of your active end users

Webhooks — Relay API

Full reference: Webhooks API reference.

MethodEndpointDescription
POST/v1/relay/messagesPublish an event to every endpoint subscribed to its event_type
GET/v1/relay/messagesList events sent by your application, newest first
GET/v1/relay/messages/{msg_id}Fetch a single event by id — status is accepted, not a delivery outcome

Subscriber endpoints — the URLs Relay delivers to — are managed in the dashboard under Webhooks, rather than through the API key surface. The same page holds the delivery log — each message's attempts, the payload as it was sent, and the recipient's response — and the replay controls: Resend on a failed attempt, and Replay failed on an endpoint, which goes back at most 14 days. No API key route resends a delivery.

Scheduled jobs — Clockwork API

Full reference: Scheduled jobs API reference.

MethodEndpointDescription
GET/v1/clockwork/jobsList cron jobs
POST/v1/clockwork/jobsCreate a cron job
PATCH/v1/clockwork/jobs/{job_id}Update a cron job — schedule, target, or paused state
DELETE/v1/clockwork/jobs/{job_id}Delete a cron job
GET/v1/clockwork/jobs/{job_id}/executionsExecution history for a cron job
GET/v1/clockwork/delayedList one-shot delayed jobs
POST/v1/clockwork/delayedSchedule a one-shot delayed job
DELETE/v1/clockwork/delayed/{job_id}Cancel a delayed job before it fires
GET/v1/clockwork/delayed/{job_id}/executionsExecution history for a delayed job

Clockwork is the one engine with a 1:1 session-cookie mirror at /dashboard/clockwork/* — same bodies, same responses, different auth (error bodies aside: the keyed routes use the standard error envelope). The route mapping table has the pairs.

Telegram sign-in — Passepartout API

Full reference: Telegram sign-in API reference.

MethodEndpointDescription
POST/v1/passepartout/login/startBegin a login attempt; returns a nonce and a Telegram deep_link
GET/v1/passepartout/login/statusPoll a nonce until the end-user finishes in Telegram
POST/v1/passepartout/tokens/introspectValidate a ppt_ end-user access token and read its claims

Unauthenticated Endpoints

No key, no session — safe to call from a browser.

MethodEndpointDescription
GET/healthEdge gateway liveness; returns {"status":"healthy","service":"edge_gw"}
GET/public/statusLive component status behind the status page
GET/public/gate/providers/{tenant_id}The social providers a tenant has enabled — for rendering login buttons before any flow starts
*/auth/*Ory Kratos self-service routes; this is where a flow's ui.action submits
GET/auth/sessions/whoami?tokenize_as=gate_jwtA signed JWT for a signed-in end user, with their X-Session-Token — see Signed tokens
GET/auth/{tenant_id}/.well-known/openid-configurationOpenID discovery for a tenant's token issuer
GET/auth/{tenant_id}/.well-known/jwks.jsonThe public keys that verify that tenant's signed tokens

What Is Not on This Page

Three route families exist on the gateway but are not part of the public contract, and may change without notice:

  • /dashboard/* — the tenant Console API, authenticated by the ory_kratos_session cookie rather than an API key. Everything it does for Gate, Relay and Passepartout is also reachable through the keyed routes above; the exception is Clockwork, whose mirror is documented.
  • /admin/* — the operator panel behind jules.vernesoft.com.
  • /internal/* — service-to-service callbacks (Kratos webhooks, billing events). They authenticate with shared secrets and are not callable by tenants.

Next Steps