Skip to navigation

Making requests

Recommendation

Keep JSON bodies for V3 SDK operations and management changes. Keep query parameters for management listing and pagination. Health and readiness checks need no request data. Keep legacy request formats compatible with their own versions.

This describes the public SDK, Elite Key/management and bot APIs. Private dashboard/admin interfaces, provider webhooks and OAuth callbacks are outside this reference. The SDK should build and sign its requests for the developer.

API areaMethodInput location
V3 health and readinessGETNo body or query fields
V3 initialization, challenge and loginPOSTJSON body
V3 session, offline, variable, script, metadata and account operationsPOSTJSON body, including for operations without fields
New management record listsGETappId, limit and offset in the query string
New management record changesPOSTJSON body with action and its fields
Bot commandsPOSTJSON body
V1/V2 SDK endpointsPOSTTheir documented legacy JSON body
Legacy GET /api/elite-keyGETLegacy query parameters, including its key
Legacy POST /api/elite-keyPOSTapplication/x-www-form-urlencoded body, not the new JSON contract

Would JSON bodies for everything be better?

If this means POST plus JSON for every operation, it is a valid action-based design. It is already how the V3 SDK runtime works. It does not mean attaching JSON bodies to GET requests.

Advantages of POST plus JSON everywhere

  • SDKs use one request builder and one JSON parser.
  • Nested settings, arrays, booleans and long public keys are easy to represent.
  • Credentials and payload fields stay out of the URL, reducing exposure in ordinary URL logs. Request-body logging still needs redaction.
  • V3 can sign the exact JSON bytes using its existing request-proof format.
  • Large or sensitive read filters can use a documented POST search operation when that is needed.

Disadvantages

  • The HTTP method no longer tells a reader which operations only read and which change data. Names and documentation must make that clear.
  • Generic clients and infrastructure cannot treat POST reads like ordinary safe GET requests. Retries need operation-specific rules.
  • Ordinary URL-based HTTP caching, conditional GET and browser navigation are less convenient. AuthlyX currently sends no-store for these APIs, so converting existing management lists would not lose an active cache benefit.
  • Simple list filters and pagination require a request body instead of a readable query string.
  • Converting existing GET lists is a breaking contract change for integrations and documentation. It would require a migration or a new API version.
  • JSON needs serialization, content-type handling and size limits. JSON is not encryption and is not automatically faster than a query string.

There is no strong reason to change AuthlyX’s existing management list routes now. Keep the small, explicit split above. Future complex/private searches can have a separate POST JSON search endpoint if needed; no such new route is introduced by this documentation.

Rules for every new integration

  1. Use HTTPS in production. Loopback HTTP on port 4000 is for local V3 development.
  2. Use Authorization headers for new session and management credentials. Do not add passwords, license keys, bearer tokens or new Elite/Bot keys to URLs.
  3. Put non-sensitive GET list filters in query parameters and URL-encode each value. Responses can still be JSON; response format and request input location are separate decisions.
  4. Do not send a JSON body with GET. HTTP gives that content no generally defined meaning, and clients or intermediaries may reject it.
  5. Use Content-Type: application/json for V3 POST requests. Send when the documented object has no fields. V3 request bodies are limited to 16 KB.
  6. Do not accept the same field from both body and query without a documented precedence rule. The current V3 contract reads its operation fields from the body.
  7. Do not blindly retry writes such as registration, license redemption or license creation. A lost response does not prove that the server did nothing. There is no general Idempotency-Key contract here.

V3 request signatures

The current proof covers the method, URL pathname, exact body hash, nonce, timestamp and token hash. It does not cover a query string. Keep signed operation inputs in the body. Moving an input to the URL requires a protocol review and matching SDK changes; changing the README alone would not authenticate that query value.

Serialize JSON once, sign the hash of those exact UTF-8 bytes, and send those bytes. Reformatting JSON after signing changes its hash. GET management requests use account-level keys and their restrictions, not this V3 installation-proof format.

Legacy compatibility

The old Elite Key interface is an exception, not the recommended design for new integrations. Its GET route exposes the key in a URL and can perform changes selected by its action field; do not treat it as a safe browseable list URL. For an existing compatible server integration, prefer its documented form POST alternative and redact request bodies too. Do not silently change the old client contract to JSON. New integrations should use the new management endpoints with a bearer key.

V1 is end of support. V2 is legacy. Their archived routes use the old service host in their specifications; they are not implemented under the local V3 server simply because a README exists here.

Examples

The endpoint README examples use Bash/WSL cURL syntax. Replace placeholders before use. A public key must be a real Ed25519 PEM key, and protected V3 calls need freshly generated proofs; placeholder signatures will fail.

For PowerShell, use Invoke-RestMethod with an explicitly serialized body:

$body = @{ appKey = 'YOUR_APP_KEY'; version = '1.0.0' } | ConvertTo-Json -Compress
Invoke-RestMethod -Method Post -Uri 'https://api.authlyx.dev/v3/init' -ContentType 'application/json' -Body $body

Standards

Every public endpoint

EndpointInput locationQuery fields
POST /api/v1/initJSON bodyNone
POST /api/v1/loginJSON bodyNone
POST /api/v1/registerJSON bodyNone
POST /api/v1/licensesJSON bodyNone
POST /api/v1/licenses/verifyJSON bodyNone
POST /api/v1/extendJSON bodyNone
POST /api/v1/variablesJSON bodyNone
POST /api/v1/variables/setJSON bodyNone
POST /api/v1/logsJSON bodyNone
POST /api/v1/validate-sessionJSON bodyNone
POST /api/v1/chats/sendJSON bodyNone
POST /api/v1/chats/getJSON bodyNone
POST /api/v1/device-authJSON bodyNone
POST /api/v1/change-passwordJSON bodyNone
POST /api/v2/initJSON bodyNone
POST /api/v2/validate-sessionJSON bodyNone
POST /api/v2/loginJSON bodyNone
POST /api/v2/licensesJSON bodyNone
POST /api/v2/licenses/verifyJSON bodyNone
POST /api/v2/registerJSON bodyNone
POST /api/v2/extendJSON bodyNone
POST /api/v2/change-passwordJSON bodyNone
POST /api/v2/device-authJSON bodyNone
POST /api/v2/variablesJSON bodyNone
POST /api/v2/variables/setJSON bodyNone
POST /api/v2/logsJSON bodyNone
POST /api/v2/chats/sendJSON bodyNone
POST /api/v2/chats/getJSON bodyNone
GET /api/elite-keyURL query parameterskey, function, action, url_prefix, app_name
POST /api/elite-keyForm body (legacy)None
POST /api/v2/blacklist/checkJSON bodyNone
POST /v3/initializeJSON bodyNone
POST /v3/challengeJSON bodyNone
POST /v3/loginJSON bodyNone
POST /v3/registerJSON bodyNone
POST /v3/session/checkJSON bodyNone
POST /v3/session/logoutJSON bodyNone
POST /v3/offline/challengeJSON bodyNone
POST /v3/offline/permitJSON bodyNone
POST /v3/data/getJSON bodyNone
POST /v3/data/setJSON bodyNone
POST /v3/scripts/getJSON bodyNone
POST /v3/features/listJSON bodyNone
POST /v3/features/getJSON bodyNone
POST /v3/features/checkJSON bodyNone
POST /v3/metadata/listJSON bodyNone
POST /v3/metadata/getJSON bodyNone
POST /v3/metadata/setJSON bodyNone
POST /v3/metadata/checkJSON bodyNone
POST /v3/webhooks/sendJSON bodyNone
POST /v3/logs/addJSON bodyNone
POST /v3/account/passwordJSON bodyNone
POST /v3/licenses/redeemJSON bodyNone
GET /management/v1/applicationsURL query parametersappId, limit, offset
POST /management/v1/applicationsJSON bodyNone
GET /management/v1/usersURL query parametersappId, limit, offset
POST /management/v1/usersJSON bodyNone
GET /management/v1/licensesURL query parametersappId, limit, offset
POST /management/v1/licensesJSON bodyNone
GET /management/v1/devicesURL query parametersappId, limit, offset
POST /management/v1/devicesJSON bodyNone
GET /management/v1/subscriptionsURL query parametersappId, limit, offset
POST /management/v1/subscriptionsJSON bodyNone
GET /management/v1/variablesURL query parametersappId, limit, offset
POST /management/v1/variablesJSON bodyNone
POST /bots/v1/commandsJSON bodyNone