Skip to main content

Authentication & basics

Base URL​

https://<gateway-host>/main/api/v1

Replace <gateway-host> with the Analog production gateway or your self-hosted gateway hostname.

Health check​

Simple liveness probe used by clients and operators:

GET /main/api/v1/api/hello

Expect a small JSON success payload when the gateway is up. No authentication required.

Bearer authentication​

Private routes require:

Authorization: Bearer <token>

Where <token> is either:

  • a session token from device authorization, or
  • an API token copied from the user profile on the website

Do not put tokens in query strings or public repositories.

Device authorization (IDE plugins)​

Used by VS Code / JetBrains (and similar) clients so users never paste passwords into the IDE.

Flow​

Plugin                         Gateway                        Browser / user
   |  POST .../device/auth/init   |                               |
   |----------------------------->|                               |
   |  device_code, user_code,     |                               |
   |  verification_url            |                               |
   |<-----------------------------|                               |
   |                              |     open verification_url     |
   |                              |<------------------------------|
   |                              |     user signs in & confirms  |
   |  GET .../device/auth/poll    |                               |
   |----------------------------->|                               |
   |  pending / authorized+token  |                               |
   |<-----------------------------|                               |

Initialize​

POST /main/api/v1/start/device/auth/init

Typical response fields:

FieldMeaning
device_codeSecret code the plugin polls with (keep private)
user_codeShort code shown to the user
verification_urlBrowser URL to open
expires_inLifetime in seconds
intervalSuggested poll interval in seconds

Poll​

GET /main/api/v1/start/device/auth/poll?device_code=<device_code>

Poll until the response indicates authorization and includes a token, or until expiry. Respect interval to avoid hammering the API.

Browser confirmation​

The website completes confirmation while the user is logged in. Plugin authors only need init + poll; they do not call privileged confirmation APIs from the IDE process beyond what the product UI already provides.

Device authorization (Desktop Agent)​

The Desktop Agent uses a separate device-auth pair dedicated to agent clients:

  • init under the desktop-agent device-auth namespace
  • poll under the same desktop-agent namespace

Behavior matches the IDE flow (user code + browser confirmation + token), but the endpoints are not interchangeable with the plugin init/poll pair. See the Desktop Agent auth docs for product behavior.

Why two device flows?

IDE plugins and the Desktop Agent are different client classes. Keeping device sessions separate avoids mixing trust and UX between editor logins and whole-desktop tracking.

Website login (first-party)​

Email/password and OAuth (GitHub / Google) login exist for the web application. They are not the recommended integration path for third-party plugins.

Details such as bot-protection tokens, callback URLs, and session cookie formats are intentionally omitted here.

Security notes for integrators​

  • Store tokens in the editor/OS secret storage when available
  • Rotate API tokens from the profile UI if a machine is lost
  • Treat device_code like a password for the duration of the flow
  • Prefer HTTPS only; do not disable TLS verification in production clients