Authentication & basics

Base URL

https://api.testingmyproject.space/main/api/v1

Self-hosted installations replace only the 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 JWT from login or device authorization, or
• an active personal API token beginning with analog-wakatime_live_

Do not put tokens in query strings or public repositories.

Personal API tokens

Personal tokens are designed for SDKs, scripts, CLI tools, and integrations. A token is active immediately after creation, its plaintext value is returned once, and only its hash is stored by Analog WakaTime.

New tokens use this structure:

analog-wakatime_live_<token_uuid>_<32-character-random-secret>

The UUID identifies the token record. The final component is a cryptographically random URL-safe secret. This is the only supported personal API-token format.

Method	Path	Purpose
POST	/main/api/v1/create/token	Create a token and return its secret once
GET	/main/api/v1/get/token	List token metadata without exposing secrets
PATCH	/main/api/v1/update/token/{tokenUUID}	Enable or disable a token with is_active
DELETE	/main/api/v1/delete/token/{tokenUUID}	Permanently delete a token

Update body:

{
  "is_active": false
}

Set is_active to true to enable the token again. Disabling or deleting a token affects subsequent gateway requests immediately.

Save the secret once

The create response contains both token metadata and the complete plaintext analog-wakatime_live_... secret. Store the secret in a password manager, OS keychain, or deployment secret store before closing the response. The list endpoint cannot recover it later.

See Python SDK authentication, Python API-token management, Go SDK authentication, and Go API-token management for complete examples.

---

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:

Field	Meaning
device_code	Secret code the plugin polls with (keep private)
user_code	Short code shown to the user
verification_url	Browser URL to open
expires_in	Lifetime in seconds
interval	Suggested 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
• Give tokens descriptive names so they can be revoked individually
• Disable or delete a token immediately if a machine is lost
• Never commit an analog-wakatime_live_... value to Git or include it in screenshots
• Treat device_code like a password for the duration of the flow
• Prefer HTTPS only; do not disable TLS verification in production clients