> This page is for version V3 - Beta (default).
> For other versions, use one of these documentation indexes:
> - V3 - Beta (default): https://docs.authlyx.dev/v3/llms.txt
> - V2 - Legacy: https://docs.authlyx.dev/v2/llms.txt
> - V1 - End of support: https://docs.authlyx.dev/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.authlyx.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.authlyx.dev/_mcp/server.

# Making requests

> Where to send the input for every public AuthlyX endpoint.

## 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 area                                                               | Method | Input location                                                    |
| ---------------------------------------------------------------------- | ------ | ----------------------------------------------------------------- |
| V3 health and readiness                                                | GET    | No body or query fields                                           |
| V3 initialization, challenge and login                                 | POST   | JSON body                                                         |
| V3 session, offline, variable, script, metadata and account operations | POST   | JSON body, including  for operations without fields               |
| New management record lists                                            | GET    | appId, limit and offset in the query string                       |
| New management record changes                                          | POST   | JSON body with action and its fields                              |
| Bot commands                                                           | POST   | JSON body                                                         |
| V1/V2 SDK endpoints                                                    | POST   | Their documented legacy JSON body                                 |
| Legacy GET /api/elite-key                                              | GET    | Legacy query parameters, including its key                        |
| Legacy POST /api/elite-key                                             | POST   | application/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:

```powershell
$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

* [HTTP GET request semantics](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.3.1)
* [Sensitive information in URLs](https://www.rfc-editor.org/rfc/rfc9110.html#section-17.9)
* [OpenAPI parameter locations](https://spec.openapis.org/oas/v3.1.1.html#parameter-object)

## Every public endpoint

| Endpoint                            | Input location       | Query fields                                          |
| ----------------------------------- | -------------------- | ----------------------------------------------------- |
| `POST /api/v1/init`                 | JSON body            | None                                                  |
| `POST /api/v1/login`                | JSON body            | None                                                  |
| `POST /api/v1/register`             | JSON body            | None                                                  |
| `POST /api/v1/licenses`             | JSON body            | None                                                  |
| `POST /api/v1/licenses/verify`      | JSON body            | None                                                  |
| `POST /api/v1/extend`               | JSON body            | None                                                  |
| `POST /api/v1/variables`            | JSON body            | None                                                  |
| `POST /api/v1/variables/set`        | JSON body            | None                                                  |
| `POST /api/v1/logs`                 | JSON body            | None                                                  |
| `POST /api/v1/validate-session`     | JSON body            | None                                                  |
| `POST /api/v1/chats/send`           | JSON body            | None                                                  |
| `POST /api/v1/chats/get`            | JSON body            | None                                                  |
| `POST /api/v1/device-auth`          | JSON body            | None                                                  |
| `POST /api/v1/change-password`      | JSON body            | None                                                  |
| `POST /api/v2/init`                 | JSON body            | None                                                  |
| `POST /api/v2/validate-session`     | JSON body            | None                                                  |
| `POST /api/v2/login`                | JSON body            | None                                                  |
| `POST /api/v2/licenses`             | JSON body            | None                                                  |
| `POST /api/v2/licenses/verify`      | JSON body            | None                                                  |
| `POST /api/v2/register`             | JSON body            | None                                                  |
| `POST /api/v2/extend`               | JSON body            | None                                                  |
| `POST /api/v2/change-password`      | JSON body            | None                                                  |
| `POST /api/v2/device-auth`          | JSON body            | None                                                  |
| `POST /api/v2/variables`            | JSON body            | None                                                  |
| `POST /api/v2/variables/set`        | JSON body            | None                                                  |
| `POST /api/v2/logs`                 | JSON body            | None                                                  |
| `POST /api/v2/chats/send`           | JSON body            | None                                                  |
| `POST /api/v2/chats/get`            | JSON body            | None                                                  |
| `GET /api/elite-key`                | URL query parameters | `key`, `function`, `action`, `url_prefix`, `app_name` |
| `POST /api/elite-key`               | Form body (legacy)   | None                                                  |
| `POST /api/v2/blacklist/check`      | JSON body            | None                                                  |
| `POST /v3/initialize`               | JSON body            | None                                                  |
| `POST /v3/challenge`                | JSON body            | None                                                  |
| `POST /v3/login`                    | JSON body            | None                                                  |
| `POST /v3/register`                 | JSON body            | None                                                  |
| `POST /v3/session/check`            | JSON body            | None                                                  |
| `POST /v3/session/logout`           | JSON body            | None                                                  |
| `POST /v3/offline/challenge`        | JSON body            | None                                                  |
| `POST /v3/offline/permit`           | JSON body            | None                                                  |
| `POST /v3/data/get`                 | JSON body            | None                                                  |
| `POST /v3/data/set`                 | JSON body            | None                                                  |
| `POST /v3/scripts/get`              | JSON body            | None                                                  |
| `POST /v3/features/list`            | JSON body            | None                                                  |
| `POST /v3/features/get`             | JSON body            | None                                                  |
| `POST /v3/features/check`           | JSON body            | None                                                  |
| `POST /v3/metadata/list`            | JSON body            | None                                                  |
| `POST /v3/metadata/get`             | JSON body            | None                                                  |
| `POST /v3/metadata/set`             | JSON body            | None                                                  |
| `POST /v3/metadata/check`           | JSON body            | None                                                  |
| `POST /v3/webhooks/send`            | JSON body            | None                                                  |
| `POST /v3/logs/add`                 | JSON body            | None                                                  |
| `POST /v3/account/password`         | JSON body            | None                                                  |
| `POST /v3/licenses/redeem`          | JSON body            | None                                                  |
| `GET /management/v1/applications`   | URL query parameters | `appId`, `limit`, `offset`                            |
| `POST /management/v1/applications`  | JSON body            | None                                                  |
| `GET /management/v1/users`          | URL query parameters | `appId`, `limit`, `offset`                            |
| `POST /management/v1/users`         | JSON body            | None                                                  |
| `GET /management/v1/licenses`       | URL query parameters | `appId`, `limit`, `offset`                            |
| `POST /management/v1/licenses`      | JSON body            | None                                                  |
| `GET /management/v1/devices`        | URL query parameters | `appId`, `limit`, `offset`                            |
| `POST /management/v1/devices`       | JSON body            | None                                                  |
| `GET /management/v1/subscriptions`  | URL query parameters | `appId`, `limit`, `offset`                            |
| `POST /management/v1/subscriptions` | JSON body            | None                                                  |
| `GET /management/v1/variables`      | URL query parameters | `appId`, `limit`, `offset`                            |
| `POST /management/v1/variables`     | JSON body            | None                                                  |
| `POST /bots/v1/commands`            | JSON body            | None                                                  |