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.
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
- Use HTTPS in production. Loopback HTTP on port 4000 is for local V3 development.
- Use Authorization headers for new session and management credentials. Do not add passwords, license keys, bearer tokens or new Elite/Bot keys to URLs.
- 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.
- Do not send a JSON body with GET. HTTP gives that content no generally defined meaning, and clients or intermediaries may reject it.
- 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.
- 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.
- 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:

