Skip to content
telnety

API reference

Telnety's REST API exposes 33 endpoints across seven sections. All routes live under the production base URL https://api.telnety.com/v1 and require a Bearer access token unless explicitly marked otherwise. This page summarises every endpoint; the full OpenAPI 3.1 spec lands alongside the public beta and will be served at /v1/openapi.json with a Swagger UI mirror at /v1/docs.

Conventions

  • Base URL: https://api.telnety.com/v1
  • Authentication: Bearer JWT in the Authorization header. Tokens are issued as pairs (access + refresh).
  • Content type: application/json for both requests and responses; charset UTF-8.
  • Time format: ISO 8601 with UTC offset (2026-05-17T12:30:00Z).
  • Errors: { "code": "snake_case_code", "message": "Human-readable text", "details": { ... } }
  • Rate limits: 60 requests/min for authenticated routes, 10 requests/min for unauthenticated routes. Limits are announced via X-RateLimit-Remaining headers.
Example request
curl -sS https://api.telnety.com/v1/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json"
The full OpenAPI 3.1 spec is generated from the Axum route definitions and lands at /v1/openapi.json alongside a Swagger UI mirror at /v1/docs when the public API ships.

Authentication (15)

All 15 endpoints under /auth and /profile cover account creation, sign-in, password hygiene, sessions, OAuth, and the recovery flow. Tokens are JWTs issued in pairs (access + refresh) with the refresh token bound to the requesting device family for token-family revocation.

POST/auth/registerCreate a new account with email + password.
POST/auth/loginAuthenticate and receive an access + refresh token pair.
POST/auth/logoutRevoke the current token family for this device.
POST/auth/refreshExchange a valid refresh token for a fresh access token.
POST/auth/forgot-passwordBegin password reset; emails a one-time link.
POST/auth/reset-passwordComplete password reset using the token from the email link.
POST/auth/verify-emailConfirm the email address using the verification token.
POST/auth/resend-verificationRe-issue an email verification token (rate-limited).
POST/auth/change-passwordChange the password for the authenticated user.
GET/auth/sessionsList active sessions (one entry per device family).
DELETE/auth/sessions/:idRevoke a specific session by ID.
POST/auth/oauth/googleSign in or link a Google account via OAuth.
POST/auth/oauth/githubSign in or link a GitHub account via OAuth.
GET/profileReturn the authenticated user profile.
PATCH/profileUpdate profile fields (display name, locale, marketing opt-in).

Example: register

POST /auth/register
{
  "email": "engineer@example.com",
  "password": "S3cureP@ssword2026",
  "display_name": "Engineer One",
  "locale": "en-US",
  "marketing_opt_in": false
}

// 201 Created
{
  "user": { "id": "usr_...", "email": "engineer@example.com" },
  "tokens": {
    "access_token":  "eyJ...",
    "refresh_token": "eyJ...",
    "expires_in": 900
  }
}

Example: login

POST /auth/login
{
  "email":    "engineer@example.com",
  "password": "..."
}

// 200 OK
{
  "user":    { "id": "usr_...", "email": "engineer@example.com" },
  "tokens":  { "access_token": "...", "refresh_token": "...", "expires_in": 900 },
  "license": { "tier": "pro", "expires_at": "2027-05-17T00:00:00Z" }
}

Example: refresh

POST /auth/refresh
{
  "refresh_token": "eyJ..."
}

// 200 OK
{
  "access_token":  "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900
}

License (1)

Single endpoint that returns the current license payload for the authenticated user. Payloads are Ed25519-signed and validate offline for up to 14 days (the grace period) before the client requires a refresh.

GET/licenseReturn the current Ed25519-signed license payload for the user.

Example: license

GET /license
// 200 OK
{
  "tier": "pro",
  "issued_at":  "2026-05-17T00:00:00Z",
  "expires_at": "2027-05-17T00:00:00Z",
  "device_limit": 3,
  "signature": "ed25519:...",
  "payload":   "base64-encoded canonical JSON"
}

The desktop client verifies signature against the public Ed25519 key shipped with each release. A valid signature lets the client run offline for up to 14 days past the most recent verification.

Devices (2)

Two endpoints cover the device registry. A user with a Pro license has 3 device activations; a Team license has unlimited devices per user but accountable usage.

GET/devicesList devices linked to the current account.
DELETE/devices/:idDeactivate a specific device by ID.

Example: list devices

GET /devices
// 200 OK
{
  "devices": [
    {
      "id":         "dev_abc",
      "name":       "MacBook Pro (Sara)",
      "platform":   "macos",
      "last_seen":  "2026-05-17T11:55:00Z",
      "active":     true
    },
    { "id": "dev_def", "name": "Pixel 8", "platform": "android", "last_seen": "...", "active": true }
  ]
}

Billing (6)

Six endpoints implement the billing surface. Telnety uses Paddle (merchant of record) for USD billing; Paddle handles VAT and sales tax automatically based on the customer's region. All responses are denominated in USD.

POST/billing/checkoutStart a checkout session; returns a Paddle checkout URL.
POST/billing/portalReturn a customer-portal URL for self-service billing changes.
GET/billing/invoicesList paid and pending invoices for the account.
GET/billing/invoices/:idReturn one invoice with line items and PDF link.
POST/billing/payment-methodsAttach a new card or wallet to the account.
DELETE/billing/payment-methods/:idRemove a payment method.

Example: start checkout

POST /billing/checkout
{
  "plan":      "pro_monthly",
  "seats":     1,
  "billing_currency": "USD",
  "return_url": "https://app.telnety.com/billing/success"
}

// 201 Created
{
  "checkout_url": "https://sandbox-checkout.paddle.com/...",
  "expires_at":   "2026-05-17T13:00:00Z"
}

Subscriptions (3)

Three endpoints manage subscription lifecycle. Plan changes prorate immediately; cancellations remain active until period end unless ?immediate=true is passed.

GET/subscriptionReturn the active subscription (plan, seats, renewal date).
PATCH/subscriptionChange plan, seat count, or billing cadence.
DELETE/subscriptionCancel; effective at period end by default.

Example: change plan

PATCH /subscription
{
  "plan": "team_yearly",
  "seats": 8,
  "proration": true
}

// 200 OK
{
  "plan":   "team_yearly",
  "seats":  8,
  "renews_at": "2027-05-17T00:00:00Z",
  "next_invoice": { "amount": 159992, "currency": "USD" }
}

Webhooks (1)

Single inbound webhook endpoint that Paddle calls for payment events. Signatures are HMAC-SHA256 (the Paddle-Signature header) and verified against PADDLE_NOTIFICATION_SECRET; events with bad signatures return 400 and are not retried.

POST/webhooks/paddleReceive payment, subscription, and refund events from Paddle.

Example: Paddle event

POST /webhooks/paddle
Headers
  Paddle-Signature: ts=1747476000;h1=...

Body
{
  "event_type":  "transaction.completed",
  "event_id":    "evt_01h...",
  "data": {
    "id":              "txn_01h...",
    "subscription_id": "sub_01h...",
    "customer_id":     "ctm_01h...",
    "details": {
      "totals": {
        "total":    "999",            // USD minor units (cents)
        "currency_code": "USD"
      }
    }
  },
  "occurred_at": "2026-05-17T12:30:00Z"
}

// 200 OK
{ "received": true }

Telnety verifies the Paddle-Signature header (HMAC-SHA256 over the raw request body) using the shared secret in PADDLE_NOTIFICATION_SECRET before processing. Failures return 400 without retry; legitimate Paddle events retry automatically with exponential backoff.

App (1)

Single endpoint that returns the latest desktop and mobile app versions plus their download URLs and checksums.

GET/app/latestReturn the latest signed releases for desktop and mobile.

Example: latest releases

GET /app/latest
// 200 OK
{
  "desktop": {
    "version":   "1.0.0",
    "released":  "2026-05-15T00:00:00Z",
    "platforms": {
      "windows":  { "url": "https://releases.telnety.com/Telnety-1.0.0.exe",   "sha256": "..." },
      "macos":    { "url": "https://releases.telnety.com/Telnety-1.0.0.dmg",   "sha256": "..." },
      "linux":    { "url": "https://releases.telnety.com/Telnety-1.0.0.AppImage","sha256": "..." }
    }
  },
  "mobile": {
    "android": { "url": "https://releases.telnety.com/Telnety-1.0.0.apk", "version": "1.0.0" },
    "ios":     { "available": false, "eta": "v1.1" }
  }
}