# AuthlyX complete documentation This file contains the documentation content, API specifications, SDK catalog and available SDK source directly. No additional page fetch is required to read the material below. V3 is beta; V2 is legacy; V1 is end of support. Downloads and framework availability are described in the catalog. # Documentation: access-methods A sign-in method is what your customer uses to prove they have access to MyApp. You can offer license login, username and password, device login, or a combination. There is no single best choice for every product. ```mermaid flowchart TD A[You choose which methods MyApp offers] --> L[License login] A --> U[Username and password] A --> D[Device login] L --> L1[Customer enters their license, such as ADE] U --> U1[Customer enters their username and password] D --> D1[MyApp reads the configured processor or motherboard identifier] D1 --> D2[The matching identifier must be whitelisted in Devices] L1 --> C[AuthlyX checks the matching access record and app rules] U1 --> C D2 --> C C --> OK[Allowed: issue an authenticated session] C --> NO[Rejected: return the reason] ``` ## License login You create a license and give its value to the customer. MyApp submits that value when they sign in. A license can be generated in groups such as `ADE2-44R4-YY3W-554D`, but it can also be your own string, such as `ADE`. The grouped format is a convenience, not what makes a value a license. You can build a Remember me option for a license, just as you can for a username. Store credentials carefully and explain what is saved. Remembering a key does not make an expired or banned license valid. ## Username and password The customer signs in with a username and password. Some developers prefer this because it gives customers familiar login details and password-management options. A developer can create the user, or use the supported registration flow with a license. The exact registration behaviour is explained in the SDK and API references. This method is not automatically better for multiple devices. Device limits and the records you configure determine access, whichever sign-in method you offer. ## Device login MyApp sends an identifier that you have whitelisted. The customer does not type a license, username or password. For your hardware-based workflow, use the chosen motherboard or processor identifier consistently in the whitelist and the app. **Current V3 integration detail:** the API receives the configured identifier in `sid`. The SDK's Windows default helper reads a Windows account SID; it does not automatically read a motherboard or processor ID. Configure the intended identifier instead of treating the default SID as a hardware serial. See Device login. ## Offer one, two or all three Your interface can show only License login, only Username and password, or several choices. For example, MyApp might offer keys to individual customers and device login on preapproved workstations. The same application can support both. Choose the experience you want to sell and support. AuthlyX checks the record behind the selected method, its expiry and status, device limits and application policies. Your app must use the returned result before opening protected features. # Documentation: allowed-versions You release **Northstar Editor 3.2.0** after fixing a bug that caused projects to fail to save. You want users to move off `3.1.0`. Add `3.2.0` to the app's **Allowed Versions** list and remove `3.1.0` when you are ready to block it. A client on `3.1.0` then gets a `UPDATE_REQUIRED` response instead of a session. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#171717","primaryBorderColor":"#404040","lineColor":"#606060","secondaryColor":"#f5f5f5","tertiaryColor":"#ffffff","edgeLabelBackground":"#ffffff"}}}%% flowchart LR A[App sends version 3.2.0] --> C{Version in Allowed Versions?} B[App sends version 3.1.0] --> C C -->|Yes| D[Continue normal sign-in checks] C -->|No| E[Return UPDATE_REQUIRED] E --> F[App shows update instructions] ``` ## Set the allowed list 1. Open the app's **Settings → Allowed Versions** page. 2. Add each exact version string your app sends during initialization, such as `3.2.0`. 3. Keep the list empty if you want every version to pass this check. Once you add entries, only listed versions are accepted. 4. Test an allowed build and a build you intend to block before changing production access. Before removing a version, publish a working update and tell affected customers where to get it. An app that receives `UPDATE_REQUIRED` should show an update message or link. It should not close without explanation. ## How this differs from other release settings - **Allowed Versions** decides whether the version currently running may connect. - **Release Channels** decides which update link and release notes a signed-in identity receives. - **Hash Management** checks a build hash. A version string is not a fingerprint of the executable. For example, you can offer Beta `3.3.0-rc.1` to testers while both `3.2.0` and `3.3.0-rc.1` remain allowed. When you later remove `3.2.0`, it is rejected even if the customer is still assigned to Stable. # Documentation: api-overview ## Base URL The API listens at `https://api.authlyx.dev`. V3 runtime requests use `/v3/`. Server-side record management uses `/management/v1/`; that management version is separate from the SDK protocol version. ## HTTP methods The endpoint reference shows the actual method beside every route. Health endpoints use **GET**. V3 SDK actions use **POST** with `Content-Type: application/json` and a JSON body. Record management uses **GET** to list and **POST** with an action to change data. There are no public PUT routes in the current rebuild. ## Authentication | API | Credential | Where to use it | | --- | --- | --- | | V3 initialization | AppKey and app version | Customer application | | V3 sign-in | AppKey, credentials and installation challenge proof | SDK handles the proof | | Protected V3 operations | Session bearer token plus installation request proof | SDK handles signing | | Management | Account-level Elite Key with permissions | Developer server | | Bot commands | Account-level Bot Key with permissions | Self-hosted bot server | Never include an Elite Key or Bot Key in customer software. An AppKey identifies an application and cannot replace a management key. ## Responses Protected V3 responses contain `success`, `code`, `message`, `data`, `requestId` and `verification`. Verify the response first, then read `success` and the stable code. The SDK returns a language-appropriate result object. ## Try a request ```bash ``` ```bash curl -X POST https://api.authlyx.dev/v3/initialize \ -H "Content-Type: application/json" \ -H "X-AuthlyX-Nonce: 0123456789abcdef0123456789abcdef" \ -d '{"appKey":"YOUR_APP_KEY","version":"1.0.0"}' ``` Use a fresh random nonce in real requests. This command shows the HTTP shape; use the SDK or a verified implementation to validate signatures. Protected endpoint examples also need valid installation proof headers. A copied bearer token alone is insufficient. ## API explorer Fern's API reference provides an explorer. Public health/init requests are easy to test. Protected operations require fresh proof, so pasting placeholder headers will fail. Use the SDK to generate and sign requests. In published docs, `localhost` refers to the reader's own computer, not AuthlyX's server. V1 and V2 references are archived separately. Their explorers are disabled so archived examples are not mistaken for the current V3 service. Internal dashboard, admin, OAuth callback and payment-provider webhook routes are not customer integration APIs. Examples use made-up accounts, keys and tokens. Use your own credentials and generate fresh request signatures. Example signatures are not production credentials. # Documentation: app-credentials ## Which key belongs in your app? MyApp needs an AppKey so AuthlyX knows which application is connecting. That key can be included in distributed customer software. It identifies the app; it does not give everyone permission to manage the developer account. An Elite Key or Bot Key is different. Those credentials authorize management operations according to their permissions. Keep them on a server or in the authorized bot service, never in a desktop binary, browser bundle or public repository. ```mermaid flowchart LR A[MyApp customer software] -->|AppKey and login proof| B[Client API] C[Developer's private server] -->|Scoped management key| D[Management API] B --> E[Check customer access] D --> F[Manage permitted records] ``` ## An AppKey is not an unbreakable app secret Someone who can inspect the customer's software can read embedded values. AppKeys therefore cannot prove that an HTTP request came from an unmodified program. AuthlyX uses authenticated identities, installation proof and server-side authorization to decide access. Use the AppKey and version from the same application as your test license. Initialize first, then log in. Never paste a management key into the AppKey field to fix a failed login. ## Rotating credentials Rotate management keys when a server or bot credential may have leaked. Give each integration a descriptive name, only the permissions it needs and an expiry when appropriate. Revoke old keys after updating the service. AppKey rotation also needs a release plan: existing software may still contain the previous key. Test the transition before changing a live app. Verification public keys are a third category: they let the SDK verify server signatures and do not grant management access. Keep trusted verification keys in step with the API's signing-key rotation. ## Check your release Search the compiled frontend configuration and repository for management credentials. Confirm that customer software can authenticate but cannot create arbitrary licenses or inspect another account. The warning in API Reference applies to both Elite Keys and Bot Keys. # Documentation: app-hashes ## A real release example Say you ship **Northstar Editor 2.3.0**. You want the copy you built and tested to sign in, but you do not want an old or changed executable to pass the same check. SHA-256 makes a fingerprint from the exact bytes in one file. If one byte changes, the fingerprint changes too. AuthlyX compares the hash sent by the SDK with the hashes you approved for that app. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#171717","primaryBorderColor":"#404040","lineColor":"#606060","secondaryColor":"#f5f5f5","tertiaryColor":"#ffffff","edgeLabelBackground":"#ffffff"}}}%% flowchart LR A[Build Northstar Editor 2.3.0] --> B[Calculate SHA-256 of Northstar.exe] B --> C[Add hash to this app in AuthlyX] C --> D[Enable hash checking] E[Customer starts Northstar.exe] --> F[SDK sends configured build hash at sign-in] F --> G{Hash is on the app allowlist?} G -->|Yes| H[Continue normal access checks] G -->|No| I[Reject sign-in] ``` Hash checking is one extra check. It does not prove that a desktop app cannot be changed, and it does not replace license, user or device checks. ## Get the hash for the file you ship Build the file you want to approve, then run this in PowerShell: ```powershell Get-FileHash -LiteralPath '.\MyApp.exe' -Algorithm SHA256 ``` For example, if the SDK reports the hash of `Northstar.exe`, calculate the hash of `Northstar.exe`. Do not calculate the ZIP hash unless your app actually reports the ZIP hash. Copy the 64-character Hash value from PowerShell. ## Add it to AuthlyX 1. Open Northstar Editor in the dashboard and go to Settings. 2. Open Hash management. 3. Add the SHA-256 hash of the approved build. 4. Enable Hash checking in this tab and save. 5. Configure the SDK's build-hash option with the same 64-character value. This is the `buildHash` sent during sign-in. It must describe the same file you hashed above. 6. Test the approved build, then test a changed file. A request that omits the hash must be rejected while checking is enabled. ## Release another build Before sending version 2.3.1 to customers, calculate the new executable's hash and add it too. Keep the 2.3.0 hash while customers still need that build. Remove it only when you are ready for 2.3.0 to fail this check. The version text (`2.3.0`) and the SHA-256 fingerprint are separate values. # Documentation: app-logs ## Record an event from your software MyApp may need to record that a customer completed a task or that a protected operation failed. Send an app log through the SDK or Client API. Use a short message that helps the developer investigate the event. ```mermaid flowchart LR A[Signed-in MyApp app] -->|Send log| B[AuthlyX validates session] B --> C[Store within the developer plan's log allowance] C --> D[Activity: App Logs] B --> E[Forward to selected webhooks when configured] ``` ## Storage and forwarding are separate choices Plus can store up to 5,000 app logs; Elite can store up to 10,000. At the storage limit, older stored entries are replaced as new ones arrive. Do not use app logs as an unlimited archive. App logs appear under Activity, in the App Logs tab. The developer can delete their app logs. Recent Activity is a different feed of dashboard actions and is not the SDK logging endpoint. A webhook destination can receive configured log events as well. Sending to a webhook does not require exposing its URL in customer software: the software talks to AuthlyX, and AuthlyX delivers to the configured destination. Use delivery history to investigate webhook failures separately from log creation. ## What should be logged? A useful message is `Export failed: unsupported image format` with a non-sensitive operation identifier. Avoid passwords, complete license keys, session tokens, private metadata, payment details and whole customer documents. Logs can be read by authorized staff and may be forwarded to external services you configure. ## Test the whole route Send a test log while signed in. Confirm it appears under the correct application and cannot be read through another account. End the session and attempt another log: the rejected session must not keep adding entries. If forwarding is enabled, check the destination's Deliveries tab and verify the signature at your receiving server. Current log storage is a paid-plan feature. Handle the API's rejection on unsupported plans; a successful initialization does not grant logging rights. # Documentation: app-versions ## Version and hash are different The version is a label such as `1.0.0` that your program sends when connecting. A hash identifies the contents of a file. Changing the version label does not change or verify the file. ## Set allowed versions 1. Open the app, then Settings and Version whitelist. 2. Add the version strings you want to allow. 3. Enable the version whitelist and save it. 4. Use the matching version in the SDK constructor. 5. Test an allowed version and an older version that is not on the list. Use the exact version string. Add the next version before releasing it, and keep the old entry until you want customers to stop using it. For a normal update notice, configure the app's new version and download link as well. # Documentation: cloud-values Store a value in App data, then read it from your SDK. For example, store a support URL or a maintenance message. Change it in the dashboard and the app receives the new value the next time it reads it. No rebuild is needed. Cloud variables belong to the application. Metadata belongs to one signed-in user, license or device. Use a cloud variable for a setting shared by all customers. Use metadata for a setting that differs per customer. Reading an app value requires a valid session. Do not put server passwords or private API keys in a value sent to client software. In C#, `getVariable("download_url", result => { ... })` returns through a callback. Read the value from `result.data` only when `result.ok` is true. On failure, inspect `result.code` and show `result.message` if appropriate. ## Add a cloud variable 1. Open your app and go to App data, then the values tab. 2. Add a variable name, such as `support_message`. 3. Enter its value, such as `Contact support before reinstalling`. 4. Save it, then fetch that exact name from your signed-in application. ```csharp app.getVariable("support_message", result => { if (result.ok) messageLabel.Text = result.data; else messageLabel.Text = result.message; }); ``` ## Change it later Edit the value in the dashboard and save. The next fetch gets the new value. A value already copied into a local variable does not update itself: your app must fetch again when it needs a fresh value. For a maintenance message, you might read it after login or during a scheduled refresh. # Documentation: cloud-variables Suppose Northstar Editor needs a maintenance notice on Monday morning. If the text is hardcoded into the app, you must rebuild and send a new download. Put the text in a Cloud Variable called `maintenance_message` instead. The app reads it after sign-in. Change the text in AuthlyX and the next read returns the new message. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#171717","primaryBorderColor":"#404040","lineColor":"#606060","secondaryColor":"#f5f5f5","tertiaryColor":"#ffffff","edgeLabelBackground":"#ffffff"}}}%% flowchart LR A[Developer changes maintenance_message in dashboard] --> B[Northstar reads it after sign-in] B --> C[AuthlyX returns the saved text] C --> D[App shows the notice] A --> E[Developer edits the text] E --> F[Next read returns the edited text] ``` ## Add one 1. Open **App Data → Cloud Variables** for your app. 2. Add the key `maintenance_message` and a value such as `Maintenance starts at 9 PM UTC.` 3. Leave **Allow remote updates** off if only dashboard edits should change it. 4. In the app, read the key after sign-in and show the returned text. 5. Change the value in the dashboard and read it again. The app receives the new value on that next read. ```csharp app.getVariable("maintenance_message", result => { if (result.ok) Console.WriteLine(result.data); else Console.WriteLine(result.message); }); ``` The value is shared by everyone using that app. Editing it does not reach into a value already held in memory. Your app must read it again, for example the next time a screen opens or after sign-in. ## Allow remote updates only when needed Turn on **Allow remote updates** when an authorized app request should change the existing value. For example, a trusted admin screen in Northstar might update a shared support URL. Leave it off if the dashboard is the only place that should change the setting. Cloud Variables are readable by the app, so every customer who can read one can see its value. Do not store database passwords, private API keys or customer-specific data there. Use identity metadata for a value that differs by user, license or device. # Documentation: connection-errors ## Start with the returned code AuthlyX returns a stable code and a readable message. Developers can customize many server messages, so application logic should check the code or success result rather than compare English sentences. ```mermaid flowchart TD A[Request fails] --> B{Did a verified server reply arrive?} B -->|No| C[Check network, endpoint and trusted keys] B -->|Yes| D[Read the returned code] D --> E[Correct credentials, access policy or identity status] C --> F[Use valid offline access only if already permitted] ``` ## Invalid AppKey Copy the AppKey from the same application as the license or user. Remove accidental spaces and check that the SDK points to the intended local or production API. An old owner ID or app secret is not a V3 AppKey. Rotating the key does not automatically update installed software. ## Device limit reached Open the identity's linked devices. Confirm the configured device limit and remove a device only when the developer's replacement policy permits it. Repeatedly generating a new installation key is not a valid workaround: it can trigger an installation-key-change rejection. ## Session ended, expired or revoked Ask the customer to sign in again after resolving the underlying status. If the identity is banned, paused or expired, simply repeating initialization will not restore access. Stop protected requests when the server definitively rejects the session. ## Signature failure Confirm the SDK trusts the correct public verification key for this API. Proxies must not modify signed response data. Direct clients must sign the exact request bytes, method and path with a fresh nonce and server-aligned timestamp. Never disable signature verification to make an error disappear. ## Country blocked or reputation lookup unavailable Review the application's Access Policies. A blocked-country decision and an unavailable VPN lookup are different failures. Check trusted proxy settings before changing the customer's access rules. ## Update required Compare the customer's version with Allowed Versions and the assigned release channel. A download URL in a release does not automatically make that version allowed to connect. ## Protected storage unavailable Check that the application runs under a normal supported user profile and can access its configured protected store. Do not replace the store with plaintext or silently create a new installation identity. Preserve the error and let the customer resolve the environment issue. When reporting a problem, include the SDK/runtime version, API hostname, returned code and request ID. Remove passwords, tokens and full license keys from the report. # Documentation: create-account Create one AuthlyX account to manage your applications. You do not need a separate dashboard account for every product or customer. ## Sign up 1. Open the dashboard and choose **Create an account**. 2. Enter the details requested on the form. Use an email address you can access. 3. Complete any verification requested during sign-up, then sign in. Use your own account details here. Customer usernames and licenses are created inside an application later. ## Check your account Open your profile menu to see your current plan. Open **Account settings** to check your name and email, then review the options under **Security**. If other people will help manage your apps, give them their own staff access when your plan supports it. Sharing your password makes it harder to control access or know who changed something. ## Choose a plan when you need it You can start by creating an application and testing a sign-in. Check **Plan & billing** for the current limits and supported features before relying on a paid feature. Limits shown in your account take precedence over examples in a guide. Your AuthlyX billing plan and the plans you create for your customers are different. The first controls your AuthlyX account limits. Customer plans organize access inside your own application. Continue with Create an application. # Documentation: create-application An application keeps one product's users, licenses, devices and settings together. For example, your photo editor and your backup tool can be separate applications under the same account. ## Create it in the dashboard 1. Open **Applications**. 2. Select **Create app**, enter a recognizable name, and create it. 3. Open the application to see its details and connection settings. The initial version is `1.0.0`. Keep the version in your integration consistent with the version you are actually shipping. ## Find the V3 connection details Reveal the app's **AppKey** and copy it into your integration. V3 uses the AppKey and your software version. Older integrations use different credentials; follow the matching API version's documentation.
ApplicationPhoto Editor
SDK version field1.0.0
CredentialThis application's V3 AppKey
Elite Keys and Bot Keys belong on your server. Do not place them in software you give to customers. ## Keep testing separate Use a test application while learning the SDK. You can ban a test license, change a policy or end a session without interrupting customers. Create test records in that application rather than trying real customer credentials. Continue with Connect your app. If you are unsure which login to build, read Choose a sign-in method. # Documentation: device-login Device login authenticates a whitelisted device identifier instead of asking the customer to type a license or username and password. You decide which identifier your integration uses, such as a processor ID or motherboard identifier, and add that exact value to the application's Devices page. ## Follow one workstation You install MyApp on a customer's workstation. The integration reads the motherboard identifier you selected. You create its device record, choose its plan, set its expiry and allow access. The next time MyApp opens, it reads the same identifier and asks AuthlyX to authenticate it. ```mermaid flowchart TD A[Developer chooses motherboard or processor identification] --> B[Read that identifier on the customer's workstation] B --> C[Whitelist the exact value in MyApp's Devices page] C --> D[Choose the device's plan, expiry and status] D --> E[Customer opens MyApp] E --> F[MyApp reads the same configured identifier] F --> G[SDK obtains a challenge and proves its installation key] G --> H[AuthlyX looks for a matching device in this application] H --> I{Whitelisted, active and allowed by app policies?} I -->|Yes| J[Issue a session tied to that device and installation] I -->|No| K[Reject login with a code and message] J --> M[MyApp uses the session for protected requests] M --> N[Heartbeat checks whether access is still valid] ``` ## Match the identifier on both sides A processor value in the whitelist will not match a motherboard value submitted by the app. Pick one strategy, use the same representation every time and test on the actual hardware you support. Do not randomly generate a new value at every launch. The current V3 API field is called `sid`; it carries the configured identifier. The name of that field does not turn a Windows SID into a motherboard serial. The current SDK default on Windows reads the Windows account SID. Hardware-based device login therefore needs a supplied identifier through the SDK's configuration. It is not automatic hardware discovery. Keep exact configuration syntax in the language's SDK reference. Do not use a SID-printing sample when your whitelist contains a processor or motherboard ID. ## Device login and linked devices are different A standalone device record is the identity used for device login. A linked device under a license or user records a device that used that license or username. Removing a linked device frees or resets that binding under the developer's rules; it does not create a standalone device-login record. ## When hardware changes A replacement motherboard, a changed operating-system account or a new identifier strategy can produce a different value. Decide how you verify a replacement request and update the approved record. Do not automatically approve every unknown identifier: that removes the purpose of whitelisting. Hardware identifiers are not passwords or cryptographic proof. Some are missing, duplicated or spoofable, especially on virtual machines. Installation signatures and server-side access checks remain necessary. Device login removes the typing step, not the need to check access. ## Test before shipping Whitelist a test identifier and confirm login succeeds. Try an unknown identifier and confirm rejection. Pause the device and check that its session stops working. Repeat after restoring it, and test the hardware-replacement process separately. # Documentation: errors ## Check codes, not messages The developer can customize many display messages in app settings. They cannot change machine-readable codes or make a denied request successful. Use `result.ok` or the HTTP response's verified `success` field to check the outcome. | HTTP status | Meaning | What your app should do | | --- | --- | --- | | 400 | Invalid request | Check the documented fields | | 401 | Invalid session, credentials or request proof | Read the code; request a new login when appropriate | | 403 | Access denied by identity, app policy or plan | Show the server message and stop the denied action | | 404 | Record, value, channel or release not found | Check the name and application | | 413 | Body too large | Keep V3 request JSON within 16 KB | | 415 | Wrong content type | Send application/json | | 429 | Rate limited | Respect Retry-After; avoid retry loops | | 503 | A required service/check is unavailable | Report a connection problem; do not extend access | ## Common V3 codes | Code | Meaning | | --- | --- | | `INVALID_REQUEST` | Missing or invalid request fields | | `INVALID_PROOF` | Missing, expired or invalid installation signature | | `REQUEST_TIME_INVALID` | Request timestamp is outside the accepted window | | `REQUEST_REPLAYED` | This request nonce was already used | | `INVALID_CREDENTIALS` | Username or password is incorrect | | `LICENSE_NOT_FOUND`, `DEVICE_NOT_FOUND` | The license key or device is not registered in this app | | `USER_BANNED`, `LICENSE_BANNED`, `MOTHERBOARD_BANNED`, `PROCESSOR_BANNED` | That user, license or device is banned | | `USER_SUSPENDED`, `LICENSE_PAUSED`, `MOTHERBOARD_PAUSED`, `PROCESSOR_PAUSED` | That user, license or device is paused | | `USER_EXPIRED`, `LICENSE_EXPIRED`, `MOTHERBOARD_EXPIRED`, `PROCESSOR_EXPIRED` | That user, license or device has expired | | `DEVICE_NOT_ALLOWED` | The license or user is locked to a different system ID | | `DEVICE_LIMIT_REACHED` | All device slots are in use | | `ACCESS_REVOKED` | Access or its binding is no longer valid | | `SESSION_EXPIRED` | Session or access deadline has ended | | `COUNTRY_BLOCKED` | Connection country is blocked | | `LOCATION_UNAVAILABLE` | Required IP country could not be resolved | | `VPN_BLOCKED` | VPN/proxy policy rejects the connection | | `IP_BLOCKED`, `SID_BLOCKED` | The IP address or system ID is on the app's blocklist | | `IP_NOT_WHITELISTED`, `SID_NOT_WHITELISTED` | The app uses an allowlist and this connection is not on it | | `UPDATE_REQUIRED` | This app version is no longer allowed; the response includes update details | | `INVALID_HASH` | This build's hash is not approved | | `APP_DISABLED` | The application is paused by its developer | | `VPN_CHECK_UNAVAILABLE` | Required reputation lookup did not complete | | `OFFLINE_DISABLED` | App has not enabled an offline window | | `CURRENT_PASSWORD_INVALID` | Current app password is incorrect | | `APP_VALUE_NOT_FOUND` | Cloud variable does not exist in this app | | `RATE_LIMITED` | Too many requests | | `SIGNING_UNAVAILABLE` | Server signing is unavailable | Each code above matches an entry on the dashboard's **Responses** page, where you can reword its message. This is a common-code list, not every application-specific response. Each endpoint lists its response status codes. Include `requestId` when asking support about a request; omit credentials and bearer tokens. ## Connection failures A local timeout cannot fetch a customized server message. SDK connection errors are separate from an explicit ban or expiry. Keep signed access only until its allowed deadline. Never close the host application automatically. # Documentation: features-metadata Features describe what a customer may use, or a product setting tied to their access. Metadata stores additional information about a plan, license, user or device. Both are named fields, but they serve different purposes. ## Start with two customer plans MyApp is a video editor. Standard customers can preview HD video and export 10 files. Professional customers get 4K previews, PDF export and 100 exports. One Professional customer has a temporary agreement for 200 exports. | Field | Standard plan | Professional plan | One Professional customer's override | | --- | --- | --- | --- | | `exportPdf` - Bool | false | true | Uses plan default | | `videoQuality` - String | HD | 4K | Uses plan default | | `dailyExports` - Integer | 10 | 100 | 200 until the agreed date | | `helpUrl` - public metadata | Standard help URL | Professional help URL | Uses plan default | | `supportCase` - private metadata | Not set | Not set | AX-4812 | A number such as `dailyExports = 100` does not automatically count exports. Your app or trusted backend must enforce the operation and maintain any usage counter it needs. ## How AuthlyX chooses the value ```mermaid flowchart TD A[Customer signs in to MyApp] --> B[Find their assigned customer plan] B --> C{Standard or Professional?} C -->|Standard| S[Defaults: HD, 10 exports, PDF disabled] C -->|Professional| P[Defaults: 4K, 100 exports, PDF enabled] S --> O[Read overrides on this license, user or device] P --> O O --> Q{Does this field have an unexpired identity override?} Q -->|Yes| V[Use the identity value, such as 200 exports] Q -->|No| W[Use the plan default, such as 100 exports] V --> R[Return the effective value to MyApp] W --> R R --> UI[MyApp uses the value for its interface and protected operations] O --> M[Resolve metadata visibility separately] M --> PUB[App-readable fields can reach the customer app] M --> PRIV[Private fields stay in authorized management tools] ``` ## Create and edit features Open the customer plan, then Features. Add a name and choose Bool, String or Integer. For example, add `videoQuality` as String. If you want fixed choices, provide allowed values such as HD, 2K and 4K. Its default must be one of those choices. Edit an identity only when that customer needs a different value. Choose an existing feature and set the override. If Professional's default later changes, an unexpired customer override still takes priority. Customers without overrides use the current default. An expiry belongs to the feature value or override you configure. It does not delete the customer's license. After an override expires, its plan default is used if available; if no valid value remains, the feature is absent. Define the fallback you want and handle missing fields in your app. ## Store additional information with metadata `helpUrl` lets MyApp open the right support page. `supportCase` can help your staff find a private investigation. Metadata can be String, Integer or Bool, but it is not automatically an entitlement simply because its value is true. Mark a field app-readable only if the customer software may see it. Anyone inspecting that software may see delivered data. Keep secrets and internal notes private. Metadata does not use a feature's allowed-values list and does not have feature expiry rules. ## Remote reads and updates Use the SDK or Client API to read effective features and app-readable metadata for the current identity. Bool checks return whether the named Bool value is true. String and Integer values should be read as values, not treated as Boolean permission checks. A metadata field may allow remote updates. The field must already exist, be app-readable and have remote writing enabled. The caller cannot use that permission to create arbitrary keys or edit another identity. Treat anything writable by customer software as untrusted input. Client sessions cannot remotely edit feature entitlements. Use the authorized management API on a trusted server when your own service needs to update a customer's features. Features require Plus or Elite; metadata requires Elite. A client-side feature check can be bypassed in a modified program. Enforce valuable server operations on your own trusted backend too. # Documentation: how-authlyx-works AuthlyX gives developers a server and dashboard for managing access to their software. Licensing is one part of it. You can also manage users and approved devices, customer plans, remote app data, releases, webhooks and management integrations. ## The three parts - **Dashboard:** where you create applications, define access and change settings. - **API:** checks requests against the application's stored records and rules. - **SDK:** handles the API protocol in your application's language and returns results to your code. Developers can also call the HTTP API directly. ```mermaid flowchart TD DEV[You manage MyApp in the dashboard] --> ACCESS[Licenses, users, devices and customer plans] DEV --> DATA[Cloud variables, scripts, features and metadata] DEV --> RELEASE[Release channels and Allowed Versions] DEV --> EVENTS[Webhooks, logs and management integrations] APP[Customer opens MyApp] --> API[MyApp connects through an SDK or direct API requests] ACCESS --> API DATA --> API RELEASE --> API API --> RESULT[Your code receives access decisions and requested data] API --> EVENTS RESULT --> UI[MyApp decides what to show and which operations to allow] ``` ## Access and licensing You create the records your customers use to sign in: licenses, usernames and passwords, or whitelisted devices. Each record can have its own expiry and device limits. A successful login creates a session; later requests are checked against that session and the current rules. A license is not necessarily a long random string. It is a value you issue and AuthlyX checks. You can generate a key or use your own value. See Choose how customers sign in for the alternatives and Sessions and heartbeats for what happens after login. ## Plans and identity data Your customer plans describe what you offer within MyApp. Features can represent permissions or values such as video quality. Metadata stores additional information about a plan or identity; app-readable fields can be fetched remotely, while private fields stay out of the customer app. These customer plans are separate from your own Free, Basic, Plus or Elite AuthlyX billing plan. ## App data and releases Cloud variables let MyApp read shared values you can change without rebuilding. Scripts deliver verified text for your app to interpret. Release channels let different customers receive different update details, while Allowed Versions controls which running versions may connect. ## Events and operations Webhooks send selected events to your services. App logs help you investigate events reported by customer software. Team permissions let authorized staff or resellers manage permitted work without sharing your own account credentials. AuthlyX does not build your login screen, execute downloaded scripts, install updates or decide your product's pricing. Your application handles its own interface and business operations. Use the guides for the behaviour, SDKs for language examples, and API Reference for HTTP fields and responses. # Documentation: management-overview ## Pick the right key Create account-level keys in API Keys. An Elite Key requires a plan with Elite API access. A Bot Key requires a plan with a supported bot. Keys can have expiry dates, scopes and source restrictions. Keep them on your server and revoke them if exposed. Send the key as `Authorization: Bearer YOUR_MANAGEMENT_KEY`. An AppKey or SDK session token cannot replace it. ## Permissions Permissions use `resource.action`, for example `licenses.create` or `applications.info`. The API checks the account's active plan and the required permission on every request. A key with list access cannot silently gain create, ban or delete access. ## Read records Use `GET /management/v1/licenses?appId=APP_ID&limit=50&offset=0`. Read `data` and `nextOffset`; when `nextOffset` is null there is no next page. Results are scoped to the key's owner and omit secret-like fields. ## Change records Use POST on the resource path with an action. For example: ```json { "action": "create", "appId": "YOUR_APP_ID", "values": { "subscription": "Default", "expiryDays": "30", "devices": "1" } } ``` For licenses, omitting `values.name` generates a key. The default is four groups of four characters. `keyGroups` and `keyLength` each accept 3 to 5. `subscription` is the app plan name, not the developer's AuthlyX billing plan. For edit/delete, include the record ID and its app ID. The API reference lists supported actions for each resource. Changes are audited. Browser origin checks restrict requests but do not prove a caller's identity. ## Bot commands `POST /bots/v1/commands` accepts a Bot Key. It supports apps, status, license, pause, resume, ban and unban. Permissions still apply. Hosted Discord and Telegram callbacks validate provider signatures/secrets and are not generic customer API endpoints. ## Current scope These public management endpoints cover applications, users, licenses, devices, plans and cloud variables. They do not expose the private admin dashboard or every internal settings mutation. Do not build integrations against dashboard cookie endpoints. # Documentation: migration V3 uses an AppKey and app version instead of the older owner ID, application name, version and secret integration. It also binds sign-in sessions to an installation key and verifies server responses. Create a separate V3 test integration. Test all three sign-in methods you use, pause and ban behavior, expiry, device resets, logout, network loss, and update prompts. Do not silently change a V2 client to V3 by replacing only its base URL. V2 remains documented under Legacy. V1 is archived under End of Support. The version labels do not delete old endpoints or migrate existing customer records by themselves. Plan your client rollout and communicate any future service retirement separately. Keep the old integration working until your customers have a tested migration path. Pin the SDK version you ship so later beta changes cannot silently change your application. ## Move one application first Suppose MyApp already has 200 customers using its V2 license login. Keep that application and its customer records. Create a V3 test build using the AppKey for MyApp. Do not create a second application and expect the original licenses to appear there automatically. ```mermaid flowchart LR A[Existing MyApp customers and records] --> B[V2 app releases keep their old integration] A --> C[New MyApp build uses V3 AppKey] B --> D[Same server-side access records] C --> D D --> E[Ban, pause and expiry stay consistent] ``` ## Replace the integration, not just the URL V2 initializes with owner ID, application name, version and secret. V3 uses AppKey and version, plus installation proof during authentication. Its session token and request signing are different. An old V2 SDK cannot speak V3 just because its base URL ends in `/v3`. Download the current V3 SDK, follow its dependency instructions and make one successful test login. Check how the language exposes results and `userData`. Keep callbacks and UI updates appropriate to your framework. ## Preserve customer access Use the same license keys and usernames already stored on the original application. Existing password hashes must be verified by the server's compatible password handling; customers should not need plaintext password exports. Check device bindings before shipping: a different identifier strategy can make an existing machine look like a new device. A V2 online session is not a V3 session. The new build signs in again and enrolls its installation proof. Do not copy an old session token into the new client or silently reset all customer devices to hide a migration problem. ## Test both releases together 1. Sign in from the existing V2 release and the new V3 test release using separate test identities. 2. Ban a test identity and confirm both versions reject its access. 3. Repeat with pause, expiry and device replacement. 4. Confirm cloud-variable values agree and read-only values reject remote writes. 5. Check Allowed Versions before publishing. Add the new version while keeping the old version allowed for the planned transition. 6. Check update links for Stable and Beta identities. Do not move every customer to the test channel. 7. Keep the previous installer and deployment available until the new release is proven. ## If something goes wrong Record the response code and request ID. Stop rollout, restore the previous client release where appropriate and investigate using a test identity. Do not overwrite the live database with an older backup simply because a single client fails: new customer changes may have arrived since that backup. V1 remains documented as End of support and V2 as Legacy. Those labels do not revoke customer access by themselves. Any future shutdown needs its own notice and migration deadline. # Documentation: network-policies ## Decide which connections your app accepts Suppose MyApp is licensed for customers in selected countries. A country policy lets the developer reject sign-ins from other countries. A VPN/proxy policy can separately reject connections classified by the configured reputation service. ```mermaid flowchart TD A[Connection reaches AuthlyX] --> B[Resolve address using trusted proxy configuration] B --> C[Check explicit IP rules and country policy] C --> D[Apply VPN or proxy policy and its exceptions] D --> E[Continue identity authentication or reject] ``` ## Country is approximate The country comes from the observed IP address. It is not GPS and it cannot establish a person's physical location. Corporate networks, mobile carriers and VPN exit nodes can change the country an address maps to. Open the app's Access Policies to choose blocked countries and connection rules. Test an allowed country and a blocked country with known addresses. Testing only localhost does not prove that country restrictions work. ## VPN exceptions are not a general whitelist A VPN exception should allow the selected address through the VPN check without turning every other address into a denied connection. A restrictive IP whitelist has a different purpose: it limits access to the listed addresses. Country rules still apply according to the policy; a VPN exception is not a universal bypass. ## Configure the proxy correctly In production the API may receive traffic through Cloudflare or another reverse proxy. Only trust forwarding information from the proxies you explicitly configure. A caller must not be able to choose their country by supplying an arbitrary address header. If VPN detection is enabled and the reputation service cannot make a decision, the current API rejects the check rather than silently accepting an unverified result. Plan how your app explains that temporary failure. Do not describe an unavailable lookup as proof the customer uses a VPN. These checks are additional access rules. They do not replace license validation, session checks or protection of valuable operations on your own server. # Documentation: offline Offline access lets a previously authenticated customer keep using protected parts of MyApp without reaching AuthlyX for a limited time. It uses a signed permit issued while the customer is online. It is not a way for a brand-new customer to sign in for the first time without internet. This can help during a service outage, loss of internet or an unreliable connection. A slow connection may cause requests to time out; a valid offline permit can cover the interruption within its deadline. Local verification can be faster than a network round trip, but offline mode is not a replacement for online authorization whenever the server is reachable. ## How permission reaches the device You enable offline access in the app settings and choose the maximum window. The customer signs in online. While the session is valid, the client obtains a challenge, signs the proof and requests a permit. AuthlyX checks access and signs an expiry that the customer cannot legitimately extend. ```mermaid flowchart TD A[Developer enables offline access and chooses a maximum window] --> B[Customer signs in to MyApp while online] B --> C[Client requests an offline challenge] C --> D[Client proves possession of its installation private key] D --> E[Server checks identity, policy and remaining expiry] E --> F[Server signs a permit for this app, identity and installation] F --> G[SDK saves permit in protected local storage] G --> H[Later: MyApp cannot reach AuthlyX] H --> I{Valid signature, matching installation and unexpired permit?} I -->|Yes| J[Allow permitted offline use until the signed deadline] I -->|No| K[Ask customer to reconnect; keep work safe where possible] J --> L[Connection returns] L --> M[Check current server access] M --> N[Continue online or stop access if revoked] ``` ## Example: a 24-hour window A customer signs in to MyApp on Monday morning and saves a permit. You allow up to 24 hours offline. If their license expires in six hours, the permit must not grant another 24 hours beyond that expiry. The server decides the actual deadline using both the policy and remaining access. If the customer loses internet that afternoon, MyApp can verify the saved permit locally. No request can reach an offline endpoint while the network is unavailable. The challenge and permit endpoints are for issuing permission before the outage. ## Advantages - Customers can keep working through temporary internet or service failures. - Access remains bounded by a signed deadline instead of an editable local date. - Local checks avoid waiting for an unreachable server on every protected action. ## Limitations - A ban made while the customer is disconnected cannot be learned immediately. A longer window means a longer potential delay. - A customer who controls their device can modify their own program. Signatures and protected storage do not make the local machine tamper-proof. - Missing, corrupted or expired state must not silently create fresh access. - First-time authentication and obtaining a new permit still require the server. ## Reconnection and expiry When a verified server response revokes access, stop relying on the old offline permission. When the permit expires during an outage, ask the customer to reconnect. The SDK should not kill the process; your app can lock protected actions while allowing work to be saved. Check the SDK's offline-access methods for its current persistence behaviour. Do not assume every SDK saves a permit automatically. Protected Windows storage also requires a usable user profile; test it under the same user and deployment conditions as your customers. # Documentation: overview
AUTHLYX DOCUMENTATION

Control who can
use your software.

Guides, SDK examples, and API references to connect your app and manage customer access.

Get started How AuthlyX works
ApplicationNorthstar Editor
Version2.4.0
Release channelStable
License detailsActive
8F2K-4N7P-9R3W-6Q5M
PlanProfessional
Devices1 of 3
Expires30 Nov 2026
Session verified

Authentication

Connect your appChoose a sign-in methodDevice login

App data

Cloud variablesFeatures and metadataScripts

Releases

Release channelsAllowed versionsApp updates

Developers

SDK downloadsHTTP APIWebhooks

Build with AuthlyX

Connect your app. Check a license.

Initialize with your AppKey and version, then sign in with a license. The result tells your app whether access is allowed.

Read the login reference ↗

These snippets show the call sequence. See your SDK's setup guide for dependencies and supported platforms. Run blocking C++ calls on a worker thread in desktop interfaces.

```csharp using System; using AuthlyXSDK; public static AuthlyX app = new AuthlyX( appKey: "YOUR_APP_KEY", version: "1.0.0" ); app.initialize(initResult => { if (!initResult.ok) { Console.WriteLine(initResult.message); return; } app.login("YOUR_LICENSE_KEY", loginResult => { Console.WriteLine(loginResult.ok ? "Signed in" : loginResult.message); }); }); ``` ```cpp #include "AuthlyX.h" #include authlyx::AuthlyX app("YOUR_APP_KEY", "1.0.0"); auto initialized = app.initialize().get(); if (!initialized.ok()) { std::cout << initialized.message << '\n'; } else { auto login = app.login("YOUR_LICENSE_KEY").get(); std::cout << (login.ok() ? "Signed in" : login.message) << '\n'; } ``` ```javascript import { AuthlyX } from "./AuthlyX.js"; const app = new AuthlyX("YOUR_APP_KEY", "1.0.0"); app.initialize(initResult => { if (!initResult.ok) { console.log(initResult.message); return; } app.login("YOUR_LICENSE_KEY", loginResult => { console.log(loginResult.ok ? "Signed in" : loginResult.message); }); }); ``` ```python from authlyx_api import AuthlyX app = AuthlyX("YOUR_APP_KEY", "1.0.0") def on_initialized(result): if not result.ok: print(result.message) return app.login( "YOUR_LICENSE_KEY", completed=lambda login_result: print( "Signed in" if login_result.ok else login_result.message ), ) app.initialize(completed=on_initialized) ```

Explore the documentation

Protect your app

Set up build hashes and access policies.

Features and metadata

Set plan defaults and individual values.

Manage releases

Offer stable and beta updates to your customers.

API reference

Request fields, responses, and error codes.

Keep Elite Keys and Bot Keys on your server; never include them in customer software.

You are reading V3 Beta documentation. Use the version selector for V2 Legacy and V1 End of Support.

# Documentation: plans-and-access A customer plan groups the access you sell inside MyApp. You might offer Standard and Professional. A license, user or standalone device is assigned one of those plans and keeps its own expiry and device limits. These plans belong to your software. They are not your Free, Basic, Plus or Elite subscription to AuthlyX. ## Example: two plans in MyApp | Setting | Standard | Professional | | --- | --- | --- | | `exportPdf` - Bool feature | false | true | | `videoQuality` - String feature | HD | 4K | | `dailyExports` - Integer feature | 10 | 100 | | `helpUrl` - app-readable metadata | Your standard help URL | Your professional help URL | Features describe product capabilities or settings that affect access. Metadata stores additional information that can be read remotely when marked app-readable. Private metadata is only available through authorized management access. ## Assign access Create a Standard license for one customer and a Professional user for another. MyApp reads their effective features after login. The plan name is useful for display, but your code should read the actual values instead of assuming every identity on Professional has identical overrides. A Professional customer might have a temporary `dailyExports = 200` override for an event. Another customer on the same plan still receives 100. Changing one identity's override does not rename or change the plan for everyone. ## Plan defaults and identity overrides Defaults are read from the assigned plan. Existing identities using those defaults can see a newly added plan feature without being recreated. An individual override takes priority while it is valid. After an expiring override ends, the plan default applies if one exists. If neither the identity nor the plan has a field, it is absent. Your app should handle that case explicitly. Do not treat a missing field as permission to grant a paid capability. See Features and metadata for the full resolution diagram, examples and remote-write rules. # Documentation: quickstart ## 1. Get your AppKey Open Applications in the dashboard, then open your app. Reveal and copy its V3 AppKey. Copy the version your program is running, such as `1.0.0`. You do not need the old owner ID, application name or application secret for V3 SDK initialization. ## 2. Add an SDK Open the SDKs tab, choose your language and download the SDK ZIP. The download includes source and setup notes. Package names in those manifests do not mean the V3 package has already been published to a registry. C# uses one SDK entry file, `AuthlyX.cs`. Add the dependencies listed in the example project and create a shared instance: ```csharp using AuthlyXSDK; public static AuthlyX app = new AuthlyX( appKey: "YOUR_APP_KEY", version: "1.0.0" ); ``` Put the field in your own application class. Your UI, console or service decides where to call it. ## 3. Initialize ```csharp app.initialize(result => { statusLabel.Text = result.message; signInButton.Enabled = result.ok; }); ``` Here, `statusLabel` and `signInButton` represent your own UI controls. Initialization checks the application. It does not sign a customer in. ## 4. Sign in Create a license in the dashboard and use it to test: ```csharp app.login(licenseKey, result => { statusLabel.Text = result.message; if (result.ok) accountLabel.Text = app.userData.LicenseKey; }); ``` Run login after initialization succeeds. For username sign-in, use `login(username, password, callback)`. For an approved device, use `deviceLogin(callback)`. ## 5. Handle lost access Subscribe to the SDK's invalidation event and lock your protected controls when access ends. Keep unsaved work available. The SDK does not close your application or decide which page to show. ## Check a failed connection - The local API must be running on port 4000. - A phone or another PC cannot reach your PC through its own `127.0.0.1` address. - Default Windows examples use the real Windows user SID and protected Windows storage. - On other platforms, supply a supported stable identifier and protected store through the SDK options. Do not replace those with a random identifier on every launch. - The SDK must trust the signing keys of the API you are testing. Do not disable verification to make a request pass. # Documentation: release-channels Say your users have version `2.4.0`, and you want 12 testers to try `2.5.0-rc.1` first. Keep most identities on **Stable**. Move your test licenses to **Beta**. When they sign in, AuthlyX returns the latest release for the channel assigned to that identity. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#171717","primaryBorderColor":"#404040","lineColor":"#606060","secondaryColor":"#f5f5f5","tertiaryColor":"#ffffff","edgeLabelBackground":"#ffffff"}}}%% flowchart LR A[Developer publishes 2.5.0-rc.1 to Beta] --> B[Tester license is assigned to Beta] C[Customer license stays on Stable] --> D[Customer signs in] B --> E[Tester signs in] D --> F[AuthlyX returns Stable release details] E --> G[AuthlyX returns Beta release details] F --> H[App offers the Stable download] G --> I[App offers the test download] ``` The SDK reports the update details. Your app decides whether to show a button, open a browser link or download the file. AuthlyX does not install a release for the customer. ## Set up a test release 1. Open the app's **Updates** settings and keep **Stable** as the default. 2. Add a **Beta** channel with version `2.5.0-rc.1`, its download URL and release notes. 3. Open the test users, licenses or devices and assign them to Beta. Leave customers on Stable. 4. Sign in once with a test identity and once with a Stable identity. Check that the two sign-ins receive different release details. 5. When the test is approved, publish the version to Stable. Move test identities back to Stable if they should follow the public release. ## What a channel controls A channel answers: **which release details should this identity receive?** The assignment is read after sign-in, when AuthlyX knows the identity. Linked user and license records share an assignment. A plan can set the default for new identities; changing that default does not move existing identities. **Allowed Versions** answers a different question: **may the version already running connect?** A Beta identity can receive a link to `2.5.0-rc.1` while Allowed Versions still accepts `2.4.0`. If you need to stop `2.3.0` from signing in, change Allowed Versions too. ## When a channel is useful Use channels when you want a small group to test a release without changing the update shown to everyone. If every customer should receive the same release, keep one Stable channel. A channel does not select a plan, change expiry or silently downgrade a customer's app. # Documentation: request-formats ## 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 'http://127.0.0.1:4000/v3/init' -ContentType 'application/json' -Body $body ``` ## Standards - HTTP GET request semantics - Sensitive information in URLs - OpenAPI parameter locations ## 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 | # Documentation: request-signing Use the SDK unless you are implementing a new client. Signatures bind the request to an installation key; they do not prove that the software cannot be modified. ## Login challenge 1. Generate an Ed25519 key pair for the installation. Keep the private key in protected storage. 2. Send the public key to `POST /v3/challenge` with the AppKey. 3. Keep the returned `payload` string exactly as received. The challenge lasts two minutes and can be used once. 4. Normalize the login operation in this exact property order: `type`, `appKey`, `version`, `sid`, `hash`, `username`, `password`, `licenseKey`. Use empty strings for unused credentials and a missing hash. Append `email` only for registration when supplied. 5. Serialize `{ "challenge": payload, "operation": operation }` as compact JSON and sign its UTF-8 bytes with Ed25519. Base64-encode the signature. 6. Send the login operation, challenge ID and signature to `/v3/login`. The order and exact bytes matter. Do not log that proof payload: it includes sign-in credentials. The public key supplied during challenge creation determines which installation can consume it. ## Protected requests Send `Authorization: Bearer SESSION_TOKEN` and these headers: | Header | Value | | --- | --- | | `X-AuthlyX-Nonce` | Fresh lowercase hexadecimal nonce, 32 to 128 characters | | `X-AuthlyX-Timestamp` | Server-aligned Unix milliseconds as a 13-digit string | | `X-AuthlyX-Signature` | Base64 Ed25519 signature | Sign the compact JSON object below in this property order: ```json { "type": "authlyx.request.v3", "method": "POST", "path": "/v3/session/check", "bodySha256": "SHA256_OF_EXACT_BODY_BYTES", "nonce": "FRESH_NONCE", "timestamp": "UNIX_MILLISECONDS", "tokenHash": "SHA256_OF_SESSION_TOKEN" } ``` The hash values are lowercase hexadecimal. The timestamp is a string, not a JSON number. The signature covers the exact method, pathname, body hash, nonce, time and token hash. The server rejects requests outside its two-minute timestamp window and rejects reused nonces within their retention window. A session stays tied to its original application, identity, system ID and installation public key. Adding another username to a request cannot change who the session represents. ## Verify a server response Verify `verification.signature` over the exact UTF-8 `verification.signedPayload` using the trusted Ed25519 key identified by `keyId`. Then check its HTTP status, request method, path, nonce and body hash against your request. Check that its embedded response matches the outer response before using any access data. The SDK carries trusted public keys. A key returned by the same untrusted response cannot establish trust by itself. Keep support for planned key rotation. Health/readiness responses are not signed. Signing failures may return an unsigned `SIGNING_UNAVAILABLE` response; that must never grant access. ## Offline permit proof An offline challenge uses the existing session's installation key. Its operation is `{ "action": "offlinePermit", "sessionId": "CURRENT_SESSION_ID" }`. Sign it with the exact challenge string as above. The returned permit has its own signature and expiry checks. # Documentation: scripts Suppose a desktop game lets its developer change a weekly challenge without shipping a new game build. The developer can publish a small Lua file in AuthlyX. The game fetches the text after sign-in, verifies the AuthlyX signature, then passes the text to its own Lua interpreter. AuthlyX stores, signs and delivers the text. **AuthlyX does not run it.** The application decides whether the text is code, configuration or something else, and how to handle it. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#171717","primaryBorderColor":"#404040","lineColor":"#606060","secondaryColor":"#f5f5f5","tertiaryColor":"#ffffff","edgeLabelBackground":"#ffffff"}}}%% flowchart LR A[Developer writes challenge.lua] --> B[Publish revision in dashboard] B --> C[AuthlyX stores and signs that revision] D[Game signs in and fetches script] --> C C --> E[SDK verifies signature and app binding] E --> F[Game chooses to pass verified text to Lua] ``` ## Publish and fetch a script 1. Open **App Data → Scripts** for the app and create a stable name such as `weekly_challenge`. 2. Save and review the text, then publish a revision. 3. In the signed-in app, call `getScript("weekly_challenge")`. 4. Use the returned text only after the SDK verifies the signed response. 5. Test the new revision with a test identity before releasing your app's update. The SDK returns text. It does not know whether that text is Lua, JSON, a rules file or another format. Your app must parse it and decide what to do. A small example for a Lua-enabled game might look like: ```lua return { challenge = "collect_10_items", reward = 250 } ``` Only a game that already includes a Lua interpreter and code to read these fields can use that example. A normal C# or C++ app will not run it automatically. ## Choose scripts when - Your app already has a safe interpreter or parser for the content. - You need to update a rules file or challenge text without replacing the whole application. - You understand that customers can inspect anything delivered to their device. Use Cloud Variables for simple shared values such as a maintenance message or download URL. Use a Script when the app needs a larger structured file or code text for an interpreter it already contains. ## Limit older revisions Each publish creates a revision. You can require a minimum app version or minimum script revision, and withdraw a revision to stop new downloads of it. A customer may still have a copy they fetched earlier; withdrawal cannot erase it from their disk. Before publishing a replacement, test it with the app versions that will fetch it. If a revision is broken, withdraw it and publish a fixed revision. Do not make your app depend on being able to retrieve an old revision forever. ## Keep signing keys trusted The SDK verifies a script with public keys shipped in the SDK configuration. For a planned key rotation, release SDK configuration that trusts both the current and next public keys. Switch the server to the new private key only after customers have a version that trusts it. Keep the old public key during the transition, then remove it in a later SDK release. Signatures prove who issued the text and whether it changed in transit. They do not make unsafe code safe, hide the text from customers or stop a customer from changing their own app. Never put passwords, private keys, payment decisions or server-only rules in a script. # Documentation: sdk-methods/account Use this method after a user has signed in with a username and password. They must provide their current password and the new password. This changes the account password; it does not sign out other sessions unless your app separately ends them. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. Read Results for how each language receives the answer. ```csharp app.changePassword("CURRENT_PASSWORD", "NEW_PASSWORD", result => { Console.WriteLine(result.ok ? "Password changed" : result.message); }); ``` ```cpp auto result = app.changePassword("CURRENT_PASSWORD", "NEW_PASSWORD").get(); std::cout << (result.ok() ? "Password changed" : result.message) << '\n'; ``` ```python app.changePassword( "CURRENT_PASSWORD", "NEW_PASSWORD", completed=lambda result: print("Password changed" if result.ok else result.message), ) ``` ```javascript app.changePassword("CURRENT_PASSWORD", "NEW_PASSWORD", result => { console.log(result.ok ? "Password changed" : result.message); }); ``` ```typescript app.changePassword("CURRENT_PASSWORD", "NEW_PASSWORD", result => { console.log(result.ok ? "Password changed" : result.message); }); ``` ```java app.changePassword("CURRENT_PASSWORD", "NEW_PASSWORD") .thenAccept(result -> System.out.println(result.ok() ? "Password changed" : result.message())); ``` ```go result, err := app.ChangePassword(ctx, "CURRENT_PASSWORD", "NEW_PASSWORD") if err != nil { return err } if !result.Success { fmt.Println(result.Message) } ``` ```rust let result = app.changePassword("CURRENT_PASSWORD", "NEW_PASSWORD").await?; if !result.success { println!("{}", result.message); } ``` Never log passwords or send them to your own analytics. Use the SDK's result to show a success or error message in your own interface. # Documentation: sdk-methods/cloud-variables Cloud Variables hold named values your app can read after sign-in. If the developer allows remote updates, a signed-in client can change that value through the SDK. A dashboard edit appears on the next read; it does not push into a value already cached by the app. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.getVariable("download_url", result => { if (result.ok) Console.WriteLine(result.data); else Console.WriteLine(result.message); }); app.updateVariable("maintenance", "false", result => Console.WriteLine(result.message)); ``` ```cpp app.getVariable("download_url", [](auto result) { if (result.ok()) std::cout << result.data << '\n'; }); auto update = app.updateVariable("maintenance", "false").get(); std::cout << update.message << '\n'; ``` ```python app.getVariable("download_url", completed=lambda result: print(result.data if result.ok else result.message)) app.updateVariable("maintenance", "false", completed=lambda result: print(result.message)) ``` ```javascript app.getVariable("download_url", result => { if (result.ok) console.log(result.data); else console.log(result.message); }); app.updateVariable("maintenance", "false", result => console.log(result.message)); ``` ```typescript app.getVariable("download_url", result => { if (result.ok) console.log(result.data); else console.log(result.message); }); app.updateVariable("maintenance", "false", result => console.log(result.message)); ``` ```java app.getVariable("download_url").thenAccept(result -> System.out.println(result.message())); app.updateVariable("maintenance", "false").thenAccept(result -> System.out.println(result.message())); ``` ```go value, err := app.GetVariable(ctx, "download_url") if err != nil { return err } fmt.Println(value.Data) updated, err := app.UpdateVariable(ctx, "maintenance", "false") if err != nil { return err } fmt.Println(updated.Message) ``` ```rust let value = app.getVariable("download_url").await?; let updated = app.updateVariable("maintenance", "false").await?; println!("{}", value.message); println!("{}", updated.message); ``` Update calls only work when the variable's dashboard setting allows remote updates. Keep secrets out of cloud variables because SDK-visible values are delivered to customer software. # Documentation: sdk-methods/compatibility The SDK downloads currently cover V3 Beta. The method names and examples elsewhere in this section match those downloads. Use the version selector for V1 and V2 API reference pages; those legacy versions do not share the V3 SDK method contract. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. | SDK | Current tested target | Notes | | --- | --- | --- | | C# | .NET Framework 4.8 and .NET 8; .NET Standard 2.0 library target | The public calls are the same. Use new AuthlyX(...) if your compiler does not support target-typed construction. | | C++ | C++20 | Uses futures; do not wait on them from a UI thread. | | Python | Python 3.11+ | Async operations use asyncio; callback wrappers are also available for common calls. | | JavaScript / Node.js | Node.js 22+ | Uses Node APIs and ES modules. It is not a browser SDK. | | TypeScript | Node.js 22+ | Compile with the provided project settings. | | Java | Java 17+ | Uses CompletableFuture for network calls. | | Go | Go 1.23+ | Calls use context.Context. | | Rust | Rust 1.88+ with Tokio | Network methods are async. | The same source-level method example applies across supported target frameworks when the method exists in that SDK. Some APIs differ by language because of the language's async model or naming rules. Use the method page for exact syntax and the download page for dependencies and build steps. ## Version status - **V3 Beta:** current SDK method pages and downloads. - **V2 Legacy:** setup guides, legacy SDK usage and API reference for existing integrations. - **V1 End of Support:** archived setup guides, SDK compatibility notes and API reference. The V3 beta has not been published as a stable package for every language. Follow each download page's status and checksum. A language or framework marked Coming soon does not have a supported package yet. # Documentation: sdk-methods/extend-access Use this after a username account is signed in and the user has bought or received another license. AuthlyX applies the unused license to that account using the app's renewal rules. This is the V3 equivalent of the old V1/V2 `ExtendTime` action. The current V3 SDK method is named `redeemLicense` (or `redeemLicense` in Rust). It extends access for an already signed-in username account. It does not create a new account. Use Register to create a username account from an unused license. **SDK version:** V3 Beta. Each example assumes `app` is initialized and the user is signed in. ```csharp app.redeemLicense("NEW_LICENSE_KEY", result => { Console.WriteLine(result.ok ? "Access extended" : result.message); }); ``` ```cpp auto result = app.redeemLicense("NEW_LICENSE_KEY").get(); std::cout << (result.ok() ? "Access extended" : result.message) << '\n'; ``` ```python app.redeemLicense( "NEW_LICENSE_KEY", completed=lambda result: print("Access extended" if result.ok else result.message), ) ``` ```javascript app.redeemLicense("NEW_LICENSE_KEY", result => { console.log(result.ok ? "Access extended" : result.message); }); ``` ```typescript app.redeemLicense("NEW_LICENSE_KEY", result => { console.log(result.ok ? "Access extended" : result.message); }); ``` ```java app.redeemLicense("NEW_LICENSE_KEY") .thenAccept(result -> System.out.println(result.ok() ? "Access extended" : result.message())); ``` ```go result, err := app.RedeemLicense(ctx, "NEW_LICENSE_KEY") if err != nil { return err } if result.Success { fmt.Println("Access extended") } else { fmt.Println(result.Message) } ``` ```rust let result = app.redeemLicense("NEW_LICENSE_KEY").await?; if result.success { println!("Access extended"); } else { println!("{}", result.message); } ``` The license must be unused and allowed by the app's plan and renewal settings. After the request succeeds, the SDK refreshes the current identity data. Read User Data to see the updated expiry and plan details. # Documentation: sdk-methods/features Features describe what an identity is allowed to use. The app can read every effective feature, request one value, or check whether a named Bool feature is enabled. Plan defaults and identity overrides are resolved by AuthlyX. For example, a plan might give customers `videoQuality = "4K"` and enable the Bool feature `exportPdf`. `getFeature` reads a value. `checkFeature` asks whether a Bool feature is enabled. In every example below, the callback or local variable receives the SDK's reply. Print or inspect that reply before using its data. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.getFeatures(result => Console.WriteLine(result.ok ? result.data.ToString() : result.message)); app.getFeature("videoQuality", result => Console.WriteLine(result.ok ? result.data.ToString() : result.message)); app.checkFeature("exportPdf", result => { if (result.ok) Console.WriteLine(result.data.ToString()); else Console.WriteLine(result.code + ": " + result.message); }); ``` ```cpp auto quality = app.getFeature("videoQuality").get(); if (quality.ok()) std::cout << quality.data.dump() << '\n'; auto exportAccess = app.checkFeature("exportPdf").get(); if (exportAccess.ok()) std::cout << exportAccess.data.dump() << '\n'; ``` Each method returns a `std::future`. `.get()` waits for the request and gives you the reply. Keep that wait off a graphics or UI thread. ```python app.getFeatures(completed=lambda result: print(result.data if result.ok else result.message)) app.getFeature("videoQuality", completed=lambda result: print(result.data if result.ok else result.message)) app.checkFeature("exportPdf", completed=lambda result: print(result.data if result.ok else result.message)) ``` ```javascript app.getFeatures(result => console.log(result.ok ? result.data : result.message)); app.getFeature("videoQuality", result => console.log(result.ok ? result.data : result.message)); app.checkFeature("exportPdf", result => console.log(result.ok ? result.data : result.message)); ``` ```typescript app.getFeatures(result => console.log(result.ok ? result.data : result.message)); app.getFeature("videoQuality", result => console.log(result.ok ? result.data : result.message)); app.checkFeature("exportPdf", result => console.log(result.ok ? result.data : result.message)); ``` ```java app.getFeatures().thenAccept(result -> System.out.println(result.ok() ? result.data() : result.message())); app.getFeature("videoQuality").thenAccept(result -> System.out.println(result.ok() ? result.data() : result.message())); app.checkFeature("exportPdf").thenAccept(result -> System.out.println(result.ok() ? result.data() : result.message())); ``` ```go all, err := app.GetFeatures(ctx) if err != nil { return err } fmt.Println(all.Data) value, err := app.GetFeature(ctx, "videoQuality") if err != nil { return err } fmt.Println(value.Data) enabled, err := app.CheckFeature(ctx, "exportPdf") if err != nil { return err } fmt.Println(enabled.Data) ``` ```rust let all = app.getFeatures().await?; let value = app.getFeature("videoQuality").await?; let enabled = app.checkFeature("exportPdf").await?; println!("{all:?}"); println!("{value:?}"); println!("{enabled:?}"); ``` A client-side feature check can control what the interface shows. Your own trusted server must enforce any action that needs protection from a modified client. # Documentation: sdk-methods/heartbeats After a successful sign-in, AuthlyX needs to check that access is still valid. A **heartbeat** is that repeated check while the app is running. In the default `server` mode, the SDK does it for you using the interval sent by AuthlyX. Most apps should keep this default. `checkSession` is one check you can call yourself. Use it when your app returns from sleep, a long pause or a suspended mobile/desktop state. Do not call `checkSession` every few seconds when automatic heartbeat is already enabled. ## Check again after the app wakes `onResume` means "the app is active again, check access now." It performs the same server check as `checkSession`. It does not start a new session or extend an expired one. Call it once when your app resumes after being asleep or suspended. The SDK also checks again on its normal heartbeat schedule. Some languages use their normal naming style, such as `onResume` in Python and Rust. ## Default mode and manual mode - **Server mode** is the default. The SDK starts periodic checks after sign-in and handles session invalidation. Use this unless you have a reason to control scheduling yourself. - **Manual mode** turns off the automatic timer. Your app must call `checkSession` while it is active and `onResume` when it wakes. If you forget to call them, the app may keep showing protected screens until another request reaches AuthlyX. The default is `server`, so most apps do not need to set this option. In this mode, the SDK starts its own timer after a successful sign-in and checks again at the interval returned by AuthlyX. If your app will manage the schedule itself, choose `manual` when creating the SDK instance: | Language | Set manual mode | | --- | --- | | C# | `new AuthlyX(appKey, version, heartbeat: "manual")` | | C++ | `auto options = authlyx::defaultOptions(appKey, version); options.heartbeat = "manual"; authlyx::AuthlyX app(std::move(options));` | | Python | `AuthlyX(app_key, version, heartbeat="manual")` | | JavaScript | `new AuthlyX(appKey, version, { heartbeat: "manual" })` | | TypeScript | `new AuthlyX(appKey, version, { heartbeat: "manual" })` | | Java | `AuthlyX.Options options = AuthlyX.defaults(appKey, version); options.heartbeat = "manual"; AuthlyX app = new AuthlyX(options);` | | Go | Set `Options.Heartbeat = "manual"` before calling `authlyx.New(ctx, options)`. Check the errors from both `DefaultOptions` and `New`. | | Rust | `let options = AuthlyX::defaults(app_key, version)?.withHeartbeat("manual")?; let app = AuthlyX::withOptions(options).await?;` | These are construction examples only. Keep the normal AppKey, version, storage and trusted public keys in the SDK options. If you do not already have a reason to control the schedule, leave the setting alone. ## When access ends In `server` mode, you do not need to call `checkSession` on a timer. The SDK checks in the background. When AuthlyX confirms that the session has expired, was ended, or the identity is paused or banned, the SDK clears its signed-in state and calls the invalidation handler. Use that handler to hide protected screens and show your sign-in screen. The SDK does not close your app. Each language names that handler differently. Set it when creating the SDK, except C#, where it is an event on the `app` object: | Language | Handle a confirmed session end | | --- | --- | | C# | `app.SessionInvalidated += error => Console.WriteLine(error.Message);` | | C++ | Set `options.on_invalidated` before constructing `authlyx::AuthlyX`; print `error.what()` inside the handler. | | Python | Pass `on_session_invalidated=lambda error: print(error.message)` to `AuthlyX(...)`. | | JavaScript / TypeScript | Pass `{ onSessionInvalidated: error => console.log(error.message) }` as the third `AuthlyX` argument. | | Java | Set `options.onInvalidated = error -> System.out.println(error.getMessage());` before `new AuthlyX(options)`. | | Go | Set `options.OnInvalidated = func(err *authlyx.Error) { fmt.Println(err.Message) }` before `authlyx.New`. | | Rust | Subscribe to `app.subscribe()` and handle the `Event::SessionInvalidated(error)` event. | These handlers print the reason so the example works in a console. In a real app, replace the print call with your own code to show the sign-in screen. The SDK does not close your app. See the language tabs below for checking a session yourself. A timeout is different from an expired session: the server did not answer, so the SDK cannot confirm that access ended. Show a connection problem and keep protected actions unavailable until access is confirmed again. **SDK version:** V3 Beta. These examples use the current downloads. For what the callback, future, `await`, `CompletableFuture` and Go `err` mean, read Results. ```csharp app.checkSession(sessionResult => { if (sessionResult.ok) Console.WriteLine("Session is active"); else Console.WriteLine("Sign in again: " + sessionResult.message); }); async Task CheckAfterResume() { var resumeResult = await app.onResume(); if (!resumeResult.ok) Console.WriteLine("Sign in again: " + resumeResult.message); } ``` `checkSession` accepts a callback. `onResume()` returns a `Task`, so call it with `await` inside an async method. Call `CheckAfterResume()` from the event your framework raises when the app wakes. This SDK method does not have a callback overload for `onResume`. ```cpp void checkSessionNow(authlyx::AuthlyX& app) { auto sessionResult = app.checkSession().get(); std::cout << (sessionResult.ok() ? "Session is active" : sessionResult.message) << '\n'; } void afterAppWakes(authlyx::AuthlyX& app) { auto resumeResult = app.onResume().get(); std::cout << (resumeResult.ok() ? "Session is active" : resumeResult.message) << '\n'; } ``` Call `checkSessionNow` from your own timer only in manual mode. Call `afterAppWakes` once from your app's resume event. Do not call both for the same wake event. `.get()` waits for the future and returns the result. This is suitable for a console example. In a graphical app, wait on a worker thread, not the UI thread, or the window can freeze while the network request is running. ```python async def check_when_active(): session_result = await app.checkSession() if not session_result.ok: print(f"Sign in again: {session_result.message}") async def after_app_wakes(): resume_result = await app.onResume() if not resume_result.ok: print(f"Sign in again: {resume_result.message}") ``` `await` belongs inside `async def`. Call `after_app_wakes()` from your application's resume handler using its asyncio loop. ```javascript async function checkWhenActive() { const sessionResult = await app.checkSession(); if (!sessionResult.ok) { console.log(`Sign in again: ${sessionResult.message}`); } } async function afterAppWakes() { const resumeResult = await app.onResume(); if (!resumeResult.ok) { console.log(`Sign in again: ${resumeResult.message}`); } } ``` Call `afterAppWakes()` from the event your app uses when it becomes active again. ```typescript async function checkWhenActive(): Promise { const sessionResult = await app.checkSession(); if (!sessionResult.ok) { console.log(`Sign in again: ${sessionResult.message}`); } } async function afterAppWakes(): Promise { const resumeResult = await app.onResume(); if (!resumeResult.ok) { console.log(`Sign in again: ${resumeResult.message}`); } } ``` Call `afterAppWakes()` from the event your app uses when it becomes active again. ```java void checkSessionNow(AuthlyX app) { app.checkSession().thenAccept(sessionResult -> { System.out.println(sessionResult.ok() ? "Session is active" : sessionResult.message()); }); } void afterAppWakes(AuthlyX app) { app.onResume().thenAccept(resumeResult -> { System.out.println(resumeResult.ok() ? "Session is active" : resumeResult.message()); }); } ``` Call `checkSessionNow` from your own timer only in manual mode. Call `afterAppWakes` once from the framework's resume event. Do not call both for the same wake event. `thenAccept` gives your code the result after the request finishes without making the current thread wait. ```go func checkSession(ctx context.Context, app *authlyx.AuthlyX) error { sessionResult, err := app.CheckSession(ctx) if err != nil { return err } if sessionResult.Success { fmt.Println("Session is active") } else { fmt.Println("Sign in again: " + sessionResult.Message) } return nil } ``` The Go SDK has `CheckSession`, but no separate `OnResume` helper. Call `CheckSession(ctx)` from your app's wake handler. Python and Rust use `onResume`; C#, Java, JavaScript, and TypeScript use `onResume`. C++ uses `onResume` to follow its SDK's current naming style. ```rust let session_result = app.checkSession().await?; if session_result.success { println!("Session is active"); } else { println!("Sign in again: {}", session_result.message); } ``` `await` waits without blocking the async runtime. `?` returns an SDK/network error from the current async function. A completed response with `success == false` means AuthlyX answered but did not confirm access. When the app wakes from sleep, call `app.onResume().await?` instead of `app.checkSession().await?`. They perform the same check. Use one call for that moment, not both. In Rust, the SDK also publishes `Event::SessionInvalidated` when an automatic heartbeat confirms that access ended. Subscribe with `app.subscribe()` if you want to react to that event without manually scheduling checks. The code above prints a simple message to keep the example short. In a real app, disable paid or protected actions when access is not confirmed, keep unrelated work available, and show your own sign-in or connection screen. # Documentation: sdk-methods/initialize Initialize the SDK before sign-in. It checks the AppKey and version, establishes the installation identity and reads the app update information. It does not sign a user in. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.initialize(result => { Console.WriteLine(result.ok ? "Connected" : result.message); }); ``` ```cpp app.initialize([](auto result) { std::cout << (result.ok() ? "Connected" : result.message) << '\n'; }); ``` ```python app.initialize(completed=lambda result: print(result.message)) ``` ```javascript app.initialize(result => { console.log(result.ok ? "Connected" : result.message); }); ``` ```typescript app.initialize(result => { console.log(result.ok ? "Connected" : result.message); }); ``` ```java app.initialize(result -> System.out.println(result.ok() ? "Connected" : result.message())); ``` ```go result, err := app.Initialize(ctx) if err != nil { return err } if !result.Success { return errors.New(result.Message) } ``` ```rust let result = app.initialize().await?; if !result.success { println!("{}", result.message); } ``` After initialization, show an update option if the response says a newer version is available. Let your user choose how to get it. The SDK does not silently install the update. See Login after initialization succeeds. # Documentation: sdk-methods/login Call Login after Initialize succeeds. Choose the method that matches the access type you created in the dashboard. A username login requires both username and password. Device login sends the configured system ID as `sid`. The Windows SDK defaults use the current Windows account SID; they do not read a motherboard or processor ID. See Use device login without a login page to find the ID, add it to the dashboard and configure a custom platform ID. Each code tab lists three choices for reference. Use only one of them in your sign-in flow. Calling all three in order would attempt three sign-ins, not show three ways the same login works. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.login("YOUR_LICENSE_KEY", result => { if (result.ok) Console.WriteLine("Signed in"); else Console.WriteLine(result.message); }); app.login("YOUR_USERNAME", "YOUR_PASSWORD", result => { if (result.ok) Console.WriteLine("Signed in"); else Console.WriteLine(result.message); }); app.deviceLogin(result => { if (result.ok) Console.WriteLine("Signed in"); else Console.WriteLine(result.message); }); ``` ```cpp auto loginResult = app.login("YOUR_LICENSE_KEY").get(); if (loginResult.ok()) std::cout << "Signed in\n"; else std::cout << loginResult.code << ": " << loginResult.message << '\n'; ``` This C++ example uses a license. For username and password, replace the call with `app.login("YOUR_USERNAME", "YOUR_PASSWORD")`. For device sign-in, use `app.deviceLogin()`. Both return a future too, so call `.get()` to wait for the reply. Do that on a worker thread in a graphical app, not on its UI thread. ```python app.login("YOUR_LICENSE_KEY", completed=lambda result: print("Signed in" if result.ok else result.message)) app.login("YOUR_USERNAME", "YOUR_PASSWORD", completed=lambda result: print("Signed in" if result.ok else result.message)) async def sign_in_with_device(): result = await app.deviceLogin() print("Signed in" if result.ok else result.message) ``` ```javascript app.login("YOUR_LICENSE_KEY", result => console.log(result.ok ? "Signed in" : result.message)); app.login("YOUR_USERNAME", "YOUR_PASSWORD", result => console.log(result.ok ? "Signed in" : result.message)); app.deviceLogin().then(result => console.log(result.ok ? "Signed in" : result.message)); ``` ```typescript app.login("YOUR_LICENSE_KEY", result => console.log(result.ok ? "Signed in" : result.message)); app.login("YOUR_USERNAME", "YOUR_PASSWORD", result => console.log(result.ok ? "Signed in" : result.message)); app.deviceLogin().then(result => console.log(result.ok ? "Signed in" : result.message)); ``` ```java app.login("YOUR_LICENSE_KEY").thenAccept(result -> System.out.println(result.ok() ? "Signed in" : result.message())); app.login("YOUR_USERNAME", "YOUR_PASSWORD").thenAccept(result -> System.out.println(result.ok() ? "Signed in" : result.message())); app.deviceLogin().thenAccept(result -> System.out.println(result.ok() ? "Signed in" : result.message())); ``` ```go licenseResult, err := app.LicenseLogin(ctx, "YOUR_LICENSE_KEY") if err != nil { return err } if licenseResult.Success { fmt.Println("Signed in") } else { fmt.Println(licenseResult.Message) } ``` For username login, use `app.Login(ctx, "YOUR_USERNAME", "YOUR_PASSWORD")`. For device login, use `app.DeviceLogin(ctx)`. Each returns `(Result, error)`; check `err` first, then check `Result.Success`. ```rust let login_result = app.licenseLogin("YOUR_LICENSE_KEY").await?; if login_result.success { println!("Signed in"); } else { println!("{}", login_result.message); } ``` For username login, use `app.login("YOUR_USERNAME", "YOUR_PASSWORD")`. For device login, use `app.deviceLogin()`. Each returns a response or an SDK error. `?` handles the SDK error; `success` tells you whether AuthlyX approved the sign-in. The three calls are alternatives. Do not run all of them for one sign-in flow. Each successful login creates a session bound to the identity that signed in. See User Data for the current identity and Heartbeats for continued session checks. # Documentation: sdk-methods/logs Use the SDK log method to send a text message to the app's recent log list. The dashboard can also forward selected app events to configured webhooks. Do not include passwords, license keys, session tokens or other secrets in log text. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.log("User opened settings", result => Console.WriteLine(result.message)); ``` ```cpp auto result = app.log("User opened settings").get(); ``` ```python app.log("User opened settings", completed=lambda result: print(result.message)) ``` ```javascript app.log("User opened settings", result => console.log(result.message)); ``` ```typescript app.log("User opened settings", result => console.log(result.message)); ``` ```java app.log("User opened settings").thenAccept(result -> System.out.println(result.message())); ``` ```go result, err := app.Log(ctx, "User opened settings") ``` ```rust let result = app.log("User opened settings").await?; ``` Logs are for recent troubleshooting. They are not an audit trail for account changes. Keep the message short and avoid sending sensitive customer data. # Documentation: sdk-methods/metadata Metadata stores extra values on a plan, user, license or device. Read only metadata marked app-readable. An app can update a field only when the developer enabled remote updates for that field. Private metadata stays in the dashboard. For example, a developer might store `customer_note = "Prefers email"` and a Bool field `beta_access = true`. Read fields with `getMetadata`; use `checkMetadata` when you need to test a Bool. `setMetadata` works only for a field the developer marked remotely writable. The examples print the server reply so you can see whether the operation worked. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.getAllMetadata(result => Console.WriteLine(result.ok ? result.data.ToString() : result.message)); app.getMetadata("customer_note", result => Console.WriteLine(result.ok ? result.data.ToString() : result.message)); app.checkMetadata("beta_access", result => Console.WriteLine(result.ok ? result.data.ToString() : result.message)); app.setMetadata("display_name", "Alex", result => Console.WriteLine(result.ok ? "Metadata updated" : result.message)); ``` ```cpp auto value = app.getMetadata("customer_note").get(); if (value.ok()) std::cout << value.data.dump() << '\n'; auto check = app.checkMetadata("beta_access").get(); if (check.ok()) std::cout << check.data.dump() << '\n'; auto update = app.setMetadata("display_name", "Alex").get(); std::cout << update.message << '\n'; ``` Each method returns a `std::future`. `.get()` waits for the request and gives you the reply. Keep that wait off a graphics or UI thread. ```python async def read_and_update_metadata(): all_metadata = await app.getAllMetadata() print(all_metadata.data if all_metadata.ok else all_metadata.message) note = await app.getMetadata("customer_note") print(note.data if note.ok else note.message) beta = await app.checkMetadata("beta_access") print(beta.data if beta.ok else beta.message) updated = await app.setMetadata("display_name", "Alex") print("Metadata updated" if updated.ok else updated.message) ``` ```javascript app.getAllMetadata(result => console.log(result.message)); app.getMetadataValue("customer_note", result => console.log(result.message)); app.checkMetadata("beta_access", result => console.log(result.message)); app.setMetadata("display_name", "Alex").then(result => console.log(result.message)); ``` ```typescript app.getAllMetadata(result => console.log(result.message)); app.getMetadataValue("customer_note", result => console.log(result.message)); app.checkMetadata("beta_access", result => console.log(result.message)); app.setMetadata("display_name", "Alex").then(result => console.log(result.message)); ``` ```java app.getAllMetadata().thenAccept(result -> System.out.println(result.message())); app.getMetadata("customer_note").thenAccept(result -> System.out.println(result.message())); app.checkMetadata("beta_access").thenAccept(result -> System.out.println(result.message())); app.setMetadata("display_name", "Alex").thenAccept(result -> System.out.println(result.message())); ``` ```go func readAndUpdateMetadata(ctx context.Context, app *authlyx.AuthlyX) error { all, err := app.GetAllMetadata(ctx) if err != nil { return err } if all.Success { fmt.Println(all.Data) } else { fmt.Println(all.Message) } note, err := app.GetMetadata(ctx, "customer_note") if err != nil { return err } fmt.Println(note.Data) beta, err := app.CheckMetadata(ctx, "beta_access") if err != nil { return err } fmt.Println(beta.Data) updated, err := app.SetMetadata(ctx, "display_name", "Alex") if err != nil { return err } fmt.Println(updated.Message) return nil } ``` ```rust let all = app.getAllMetadata().await?; let value = app.getMetadataValue("customer_note").await?; let check = app.checkMetadata("beta_access").await?; let updated = app.setMetadata("display_name", serde_json::json!("Alex")).await?; println!("{}", all.data); println!("{}", value.data); println!("{}", check.data); println!("{}", updated.message); ``` Writable metadata is still customer-controlled input. Validate it before using it for a trusted operation. The SDK cannot read private metadata. # Documentation: sdk-methods/offline-access The server decides whether offline access is allowed and how long it lasts. The SDK handles the challenge, signature checks, and protected local storage. Your app may call `saveOfflineAccess` after a successful online sign-in to ask the SDK to save the permit. After that, the SDK checks the saved permit when a network request cannot reach AuthlyX. You do not create or sign the permit yourself. If the dashboard has not enabled offline access, the server will not issue one. A saved permit cannot extend its own expiry or override a ban, pause, or revoked session once the app can reach the server again. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.saveOfflineAccess(result => { Console.WriteLine(result.ok ? "Offline access saved" : result.message); }); var available = app.HasOfflineAccess; ``` ```cpp auto saved = app.saveOfflineAccess().get(); std::cout << saved.message << '\n'; auto available = app.hasOfflineAccess(); std::cout << (available ? "Offline access is available" : "No offline access") << '\n'; ``` ```python saved = await app.saveOfflineAccess() available = await app.hasOfflineAccess() print(saved.message) print("Offline access is available" if available else "No offline access") ``` ```javascript const saved = await app.saveOfflineAccess(); const available = await app.hasOfflineAccess(); console.log(saved.message); console.log(available ? "Offline access is available" : "No offline access"); ``` ```typescript const saved = await app.saveOfflineAccess(); const available = await app.hasOfflineAccess(); console.log(saved.message); console.log(available ? "Offline access is available" : "No offline access"); ``` ```java app.saveOfflineAccess().thenAccept(result -> System.out.println(result.message())); app.hasOfflineAccess().thenAccept(available -> System.out.println("Offline access: " + available)); ``` ```go saved, err := app.SaveOfflineAccess(ctx) available := app.HasOfflineAccess(ctx) ``` ```rust let saved = app.saveOfflineAccess().await?; let available = app.hasOfflineAccess().await; println!("{}", saved.message); println!("Offline access available: {available}"); ``` If the app is offline and the permit is missing, expired, or fails verification, the SDK cannot confirm access. Keep protected screens locked until the app can check with AuthlyX again. See the Offline Access guide for the dashboard policy and security limits. # Documentation: sdk-methods/register Register creates a username and password account from an unused license. It signs the new user in when the request succeeds. The developer's app must already allow registration. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.registerUser("YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY", result => { Console.WriteLine(result.ok ? "Account created" : result.message); }); ``` ```cpp auto result = app.registerUser("YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY").get(); if (result.ok()) std::cout << "Account created and signed in\n"; else std::cout << result.message << '\n'; ``` ```python app.registerUser("YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY", completed=lambda result: print("Account created and signed in" if result.ok else result.message)) ``` ```javascript app.registerUser("YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY", result => console.log(result.ok ? "Account created and signed in" : result.message)); ``` ```typescript app.registerUser("YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY", result => console.log(result.ok ? "Account created and signed in" : result.message)); ``` ```java app.registerUser("YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY") .thenAccept(result -> System.out.println(result.ok() ? "Account created and signed in" : result.message())); ``` ```go result, err := app.RegisterUser(ctx, "YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY") if err != nil { return err } if result.Success { fmt.Println("Account created and signed in") } else { fmt.Println(result.Message) } ``` ```rust let result = app.registerUser("YOUR_USERNAME", "YOUR_PASSWORD", "YOUR_LICENSE_KEY").await?; if result.success { println!("Account created and signed in"); } else { println!("{}", result.message); } ``` A license can only be used for registration once. A successful registration consumes the unused license and creates a username identity linked to it. # Documentation: sdk-methods/results Every SDK call finishes later, after AuthlyX replies. The result is the reply your code receives. It contains `ok` or `success`, an error `code`, a readable `message`, and operation data when there is any. You do not declare a magic variable named `result` at the top of your file. In the examples, `result` is a temporary name created by a callback or a local assignment. You can rename it to `loginResult`, `sessionResult` or anything clear to you. ## C# In a callback, the parameter between the parentheses is the result variable. The SDK calls this code after the network request finishes. ```csharp app.login("YOUR_LICENSE_KEY", loginResult => { if (loginResult.ok) Console.WriteLine("Access granted"); else Console.WriteLine(loginResult.code + ": " + loginResult.message); }); ``` You do not need to create `loginResult` before this call. It only exists inside the braces. In a Windows Forms app, update controls from the callback using the UI thread rules of your framework. ## C++ Network methods return a `std::future`. Calling `.get()` waits for that future and gives you its `result`. This example suits a console program or a worker thread. Do not call `.get()` on a graphical app's UI thread, because that thread will wait and the window may stop responding. ```cpp auto loginResult = app.login("YOUR_LICENSE_KEY").get(); if (loginResult.ok()) { std::cout << "Access granted\n"; } else { std::cout << loginResult.code << ": " << loginResult.message << '\n'; } ``` `auto` asks C++ to work out the result type. `.get()` is not a property on the AuthlyX result. It is the way this example waits for the future to finish and takes its value. ## Python Use `await` inside an `async def` function. It waits for this request while letting Python's event loop run other work. ```python async def sign_in(): login_result = await app.login("YOUR_LICENSE_KEY") if login_result.ok: print("Access granted") else: print(f"{login_result.code}: {login_result.message}") ``` Start `sign_in()` from the asyncio event loop used by your program. The SDK also has callback forms for common methods; in those forms, the callback parameter is the result. ## JavaScript / Node.js Put `await` inside an `async` function. It does not block Node.js's event loop. ```javascript async function signIn() { const loginResult = await app.login("YOUR_LICENSE_KEY"); if (loginResult.ok) { console.log("Access granted"); } else { console.log(`${loginResult.code}: ${loginResult.message}`); } } ``` The SDK also accepts a callback for common methods. In `app.login(key, loginResult => { ... })`, the SDK supplies `loginResult` when the request finishes. ## TypeScript The TypeScript SDK uses the same pattern as JavaScript. `loginResult` is inferred from the SDK method, so you do not need to declare its type for this example. ```typescript async function signIn(): Promise { const loginResult = await app.login("YOUR_LICENSE_KEY"); if (loginResult.ok) { console.log("Access granted"); } else { console.log(`${loginResult.code}: ${loginResult.message}`); } } ``` ## Java Java methods return a `CompletableFuture`. `thenAccept` gives you the result when the request finishes without making the current thread wait. ```java app.login("YOUR_LICENSE_KEY").thenAccept(loginResult -> { if (loginResult.ok()) { System.out.println("Access granted"); } else { System.out.println(loginResult.code() + ": " + loginResult.message()); } }); ``` The name `loginResult` is a parameter created by `thenAccept`. You can choose a different name. Avoid `.join()` on a UI thread because it waits for the request to finish. ## Go Go returns two values: `loginResult` and `err`. The method completes the request before returning. `err` is for a request or SDK failure; `loginResult.Success` tells you whether AuthlyX accepted the sign-in. ```go func signIn(ctx context.Context, app *authlyx.AuthlyX) error { loginResult, err := app.LicenseLogin(ctx, "YOUR_LICENSE_KEY") if err != nil { return err } if loginResult.Success { fmt.Println("Access granted") } else { fmt.Println(loginResult.Code + ": " + loginResult.Message) } return nil } ``` `:=` creates the two local variables. `ctx` is the request context passed into this function. A Go `error` means the request could not complete normally; `loginResult.Success == false` means AuthlyX answered but denied this sign-in. ## Rust Rust methods return `Result`. `.await` waits for the network operation inside an async function. `?` means "if the SDK returned an error, return that error from this function now." If the request completed and AuthlyX rejected access, inspect `login_result.success`. ```rust async fn sign_in(app: &AuthlyX) -> Result<(), Box> { let login_result = app.licenseLogin("YOUR_LICENSE_KEY").await?; if login_result.success { println!("Access granted"); } else { println!("{}: {}", login_result.code, login_result.message); } Ok(()) } ``` Here `?` handles a request error by returning it from `sign_in`. If AuthlyX returns a normal denial, the request itself succeeded, so the code reaches the `else` branch and prints the server message. ## A failed sign-in versus a connection problem If `ok` or `success` is false, AuthlyX answered and did not approve the operation. Show the message or handle the stable code. A timeout or network error means the SDK could not confirm the answer. Do not treat a network error as a ban, and do not unlock protected features when no successful result arrived. # Documentation: sdk-methods/scripts Scripts are versioned text published from App Data. Fetch a script after sign-in. The SDK verifies the signed release before returning its content. Your app decides what to do with the text. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.getScript("welcome_message", result => { if (result.ok) Console.WriteLine(result.data.ToString()); else Console.WriteLine(result.message); }); ``` ```cpp app.getScript("welcome_message", [](auto result) { if (result.ok()) std::cout << result.data.dump() << '\n'; }); ``` ```python app.getScript("welcome_message", completed=lambda result: print(result.data if result.ok else result.message)) ``` ```javascript app.getScript("welcome_message", result => { if (result.ok) console.log(result.data.content); else console.log(result.message); }); ``` ```typescript app.getScript("welcome_message", result => { if (result.ok) console.log(String(result.data.content)); else console.log(result.message); }); ``` ```java app.getScript("welcome_message").thenAccept(result -> System.out.println(result.ok() ? result.data() : result.message())); ``` ```go script, err := app.GetScript(ctx, "welcome_message", 0) if err != nil { return err } fmt.Println(script.Data) ``` ```rust let script = app.getScript("welcome_message", None).await?; println!("{}", script.message); ``` A script delivered to a customer's device can be inspected. Do not put secrets, private signing keys or server-only decisions in a script. Only request older revisions when your application has a reason to use them. # Documentation: sdk-methods/sign-out Call Sign Out when the user chooses to leave the account. The SDK ends the server session, stops its heartbeat and clears current user data. Keep the application open and return to your own sign-in screen. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp app.logout(result => { Console.WriteLine(result.ok ? "Signed out" : result.message); }); ``` ```cpp auto result = app.logout().get(); std::cout << (result.ok() ? "Signed out" : result.message) << '\n'; ``` ```python async def sign_out(): result = await app.logout() print("Signed out" if result.ok else result.message) ``` ```javascript const result = await app.logout(); console.log(result.ok ? "Signed out" : result.message); ``` ```typescript const result = await app.logout(); console.log(result.ok ? "Signed out" : result.message); ``` ```java app.logout().thenRun(() -> System.out.println("Signed out")); ``` ```go err := app.Logout(ctx) if err != nil { return err } fmt.Println("Signed out") ``` ```rust app.logout().await?; println!("Signed out"); ``` Rust's `logout` returns `Result<(), Error>` rather than a response containing a message. If `.await?` completes, the request succeeded; if it returns an error, Rust passes that error to the calling function. Dispose or close the SDK when the application itself shuts down. Sign Out is for ending a user's session; Close is for stopping the SDK client. # Documentation: sdk-methods/user-data After a successful login or registration, the SDK keeps the current identity data available on its client object. Read it wherever your app needs to show the signed-in person's details. It is cleared when the person signs out or AuthlyX confirms that access has ended. The exact access syntax differs by language, as shown below. The exact object shape depends on the language. The API fields use camelCase. C# exposes a typed `UserData` object with PascalCase properties. C++, Python, JavaScript, TypeScript, and Go keep the API fields and add a smaller set of PascalCase aliases. Java and Rust expose the API fields directly. ## Fields you can read | API field | C# property | What it contains | | --- | --- | --- | | `identityId` | `Id` | ID of the signed-in record. C# reads this from the login response envelope. | | `type` | `LoginType` | `user`, `license`, or `device`, describing how this identity is stored. | | `name` | `Username` | Name for this login. C# and the alias-enabled SDKs set `Username` only for user accounts. | | `licenseKey` | `LicenseKey` | Linked key when this identity has one. It can be empty for device login. Treat it as private account data. | | `email` | `Email` | Email saved on the user record, if one was provided. | | `systemId` | `SID`, `Hwid` | Device identifier used for this sign-in, when applicable. | | `plan` | `Plan`, `Subscription` | Plan name assigned to the identity. | | `expiry` | `ExpiryDate` | Access expiration time, or `null` for lifetime access. C# also exposes `IsLifetime`, calculated from this value. | | `deviceLimit` | `DeviceLimit` | Number of devices allowed for this identity. | | `registeredAt` | `RegisteredAt` | When the identity was created, when the server has that date. | | `lastLogin` | `LastLogin` | Most recent successful login time. | | `ipAddress` | `IpAddress` | Address observed by AuthlyX during sign-in. Avoid showing it unless your app needs it. | | `country` | `Country` | Approximate country derived from that address. It is not GPS or a precise location. | | `features` | `Features` | Names of enabled Boolean features inherited from the plan or set on this identity. Expired features are omitted. | | `featureValues` | `FeatureValues` | Current feature values, including text and numbers. Identity values override plan defaults. | | `metadata` | `Metadata` | Public metadata allowed for SDK access. Private metadata is not sent to the customer app. | The C++, Python, JavaScript, TypeScript, and Go SDKs currently add these PascalCase aliases: `Username`, `LicenseKey`, `SID`, `Email`, `Plan`, `ExpiryDate`, `Country`, `IpAddress`, and `DeviceLimit`. Their raw API fields, including `features`, `featureValues`, `metadata`, `registeredAt`, and `lastLogin`, remain camelCase. Java and Rust use the raw API names. C# exposes the typed properties shown in the table, plus `Hwid` as an alias for `SID` and `Subscription` as an alias for `Plan`. Some fields do not apply to every sign-in. For example, a device identity may not have a username, email, or license key. Do not assume an empty field means the login failed. ## Example data This is an example of the identity information returned after a successful sign-in. The values are illustrative; your app receives its own account data. ```json { "type": "user", "name": "maya", "licenseKey": "MAYA-4R8P-2N6K-9Q3W", "email": "maya@example.com", "systemId": "S-1-5-21-1938475620-2719458301-1209384756-1001", "plan": "Plus", "expiry": "2027-04-30T23:59:59.000Z", "deviceLimit": 3, "registeredAt": "2026-08-12T14:22:10.000Z", "lastLogin": "2026-10-28T18:41:32.000Z", "ipAddress": "203.0.113.42", "country": "NG", "features": ["exportPdf", "cloudSync"], "featureValues": { "videoQuality": "4K", "monthlyExports": 250 }, "metadata": { "customerTier": "studio" } } ``` ## Read values in your app The SDK stores this data after login. These examples read it; they do not make another API request. ```csharp var username = app.userData.Username; var plan = app.userData.Plan; var expiry = app.userData.ExpiryDate; var features = app.userData.Features; var videoQuality = app.userData.FeatureValues["videoQuality"]; ``` ```javascript const username = app.userData.Username; const plan = app.userData.Plan; const expiry = app.userData.ExpiryDate; const features = app.userData.features; const videoQuality = app.userData.featureValues.videoQuality; ``` ```typescript const username = app.userData.Username; const plan = app.userData.Plan; const expiry = app.userData.ExpiryDate; const features = app.userData.features; const videoQuality = app.userData.featureValues.videoQuality; ``` ```python username = app.userData["Username"] plan = app.userData["Plan"] expiry = app.userData["ExpiryDate"] features = app.userData["features"] video_quality = app.userData["featureValues"]["videoQuality"] ``` ```cpp auto user = app.userData(); auto username = user.value("Username", ""); auto plan = user.value("Plan", ""); auto expiry = user.value("ExpiryDate", ""); auto features = user.value("features", nlohmann::json::array()); auto quality = user["featureValues"].value("videoQuality", ""); ``` ```java var user = app.userData; String username = user.path("name").asText(""); String plan = user.path("plan").asText(""); String expiry = user.path("expiry").asText(""); var features = user.path("features"); String quality = user.path("featureValues").path("videoQuality").asText(""); ``` ```go user, err := app.UserData(ctx) if err != nil { return err } username := user["Username"] plan := user["Plan"] expiry := user["ExpiryDate"] features := user["features"] ``` ```rust let user = app.userData(); let username = user["name"].as_str().unwrap_or_default(); let plan = user["plan"].as_str().unwrap_or_default(); let expiry = user["expiry"].as_str().unwrap_or_default(); let features = &user["features"]; ``` Use Check session when you need current authorization. User Data is convenient account information; it is not a substitute for a session check or a server-side permission check. # Documentation: sdk-methods/webhooks Use Send Webhook when your client needs to pass a text or structured data event to a webhook destination configured by the developer. AuthlyX forwards the data so the destination URL and signing secret stay on the server. **SDK version:** V3 Beta. These examples use the current downloads. V1 and V2 use different APIs; choose them in the version selector. Each example assumes `app` is the AuthlyX client you created in Connect your app. When a method takes a callback, AuthlyX calls it after the reply arrives. A name such as `result` inside that callback is created there; you do not declare it at the top of your file. For C++ futures, Python or JavaScript `await`, Java futures, Go errors and Rust `?`, read Results. ```csharp var data = new JObject { ["message"] = "User completed setup", ["step"] = 3 }; app.sendWebhook("setup.completed", data, result => Console.WriteLine(result.message)); ``` ```cpp authlyx::json data = {{"message", "User completed setup"}, {"step", 3}}; auto result = app.sendWebhook("setup.completed", data).get(); std::cout << result.message << '\n'; ``` ```python app.sendWebhook("setup.completed", {"message": "User completed setup", "step": 3}, completed=lambda result: print(result.message)) ``` ```javascript app.sendWebhook("setup.completed", { message: "User completed setup", step: 3 }, result => console.log(result.message)); ``` ```typescript app.sendWebhook("setup.completed", { message: "User completed setup", step: 3 }, result => console.log(result.message)); ``` ```java app.sendWebhook("setup.completed", Map.of("message", "User completed setup", "step", 3)) .thenAccept(result -> System.out.println(result.message())); ``` ```go result, err := app.SendWebhook(ctx, "setup.completed", map[string]any{ "message": "User completed setup", "step": 3, }) ``` ```rust let data = serde_json::json!({"message": "User completed setup", "step": 3}); let result = app.sendWebhook("setup.completed", data).await?; println!("{}", result.message); ``` The developer chooses which events a destination accepts in the dashboard. The SDK does not receive the destination URL or its signing secret. Do not send files through this method. # Documentation: sdk-overview Choose a language to download its SDK source. Method examples are listed separately under SDKs > SDK methods. The available language SDKs are V3 beta source downloads. A framework using one of these languages is not automatically a tested framework integration. Entries marked Coming soon do not have a dedicated SDK package yet. ## Languages | Language or framework | Status | Download | | --- | --- | --- | | C# | V3 Beta | Download and view code | | C++ | V3 Beta | Download and view code | | Python | V3 Beta | Download and view code | | JavaScript / Node.js | V3 Beta | Download and view code | | TypeScript | V3 Beta | Download and view code | | Java | V3 Beta | Download and view code | | Go | V3 Beta | Download and view code | | Rust | V3 Beta | Download and view code | | C | Coming soon | Not available yet | | PHP | Coming soon | Not available yet | | Ruby | Coming soon | Not available yet | | Swift | Coming soon | Not available yet | | Kotlin | Coming soon | Not available yet | | Dart | Coming soon | Not available yet | | Lua | Coming soon | Not available yet | | Luau | Coming soon | Not available yet | | VB.NET | Coming soon | Not available yet | | F# | Coming soon | Not available yet | | Objective-C | Coming soon | Not available yet | | Scala | Coming soon | Not available yet | | Elixir | Coming soon | Not available yet | | Erlang | Coming soon | Not available yet | | Clojure | Coming soon | Not available yet | | Haskell | Coming soon | Not available yet | | OCaml | Coming soon | Not available yet | | Julia | Coming soon | Not available yet | | R | Coming soon | Not available yet | | Perl | Coming soon | Not available yet | | PowerShell | Coming soon | Not available yet | | Bash | Coming soon | Not available yet | | Zig | Coming soon | Not available yet | | Nim | Coming soon | Not available yet | | Crystal | Coming soon | Not available yet | | D | Coming soon | Not available yet | | Delphi / Object Pascal | Coming soon | Not available yet | | Haxe | Coming soon | Not available yet | | GDScript | Coming soon | Not available yet | | Racket | Coming soon | Not available yet | | MATLAB | Coming soon | Not available yet | | Fortran | Coming soon | Not available yet | | COBOL | Coming soon | Not available yet | | Assembly | Coming soon | Not available yet | | WebAssembly | Coming soon | Not available yet | ## Game engines | Language or framework | Status | Download | | --- | --- | --- | | Unity | Coming soon | Not available yet | | Unreal Engine | Coming soon | Not available yet | | Godot | Coming soon | Not available yet | | GameMaker | Coming soon | Not available yet | | Roblox | Coming soon | Not available yet | | Defold | Coming soon | Not available yet | | Bevy | Coming soon | Not available yet | | MonoGame | Coming soon | Not available yet | | Love2D | Coming soon | Not available yet | | RenPy | Coming soon | Not available yet | ## Desktop frameworks | Language or framework | Status | Download | | --- | --- | --- | | Windows Forms | Coming soon | Not available yet | | WPF | Coming soon | Not available yet | | WinUI | Coming soon | Not available yet | | Avalonia | Coming soon | Not available yet | | .NET MAUI | Coming soon | Not available yet | | Qt | Coming soon | Not available yet | | Electron | Coming soon | Not available yet | | Tauri | Coming soon | Not available yet | | JavaFX | Coming soon | Not available yet | | Swing | Coming soon | Not available yet | | Tkinter | Coming soon | Not available yet | | PySide | Coming soon | Not available yet | ## Web frameworks | Language or framework | Status | Download | | --- | --- | --- | | ASP.NET Core | Coming soon | Not available yet | | Blazor | Coming soon | Not available yet | | Next.js | Coming soon | Not available yet | | React | Coming soon | Not available yet | | Vue | Coming soon | Not available yet | | Angular | Coming soon | Not available yet | | Svelte | Coming soon | Not available yet | | Express | Coming soon | Not available yet | | NestJS | Coming soon | Not available yet | | Django | Coming soon | Not available yet | | Flask | Coming soon | Not available yet | | FastAPI | Coming soon | Not available yet | | Laravel | Coming soon | Not available yet | | Symfony | Coming soon | Not available yet | | Ruby on Rails | Coming soon | Not available yet | | Spring Boot | Coming soon | Not available yet | | Ktor | Coming soon | Not available yet | | Gin | Coming soon | Not available yet | | Fiber | Coming soon | Not available yet | | Phoenix | Coming soon | Not available yet | ## Mobile frameworks | Language or framework | Status | Download | | --- | --- | --- | | Flutter | Coming soon | Not available yet | | React Native | Coming soon | Not available yet | | Android | Coming soon | Not available yet | | iOS | Coming soon | Not available yet | | Ionic | Coming soon | Not available yet | | Kotlin Multiplatform | Coming soon | Not available yet | This catalog can grow as integrations are built. A Coming soon entry is not a release date or a claim that it is implemented. V1 and V2 API references remain available through the version selector. # Documentation: sessions ## A license login, from opening the app to signing out Consider a customer opening MyApp on Windows. The app starts with its AppKey and version. Initialization returns application information and update settings. It does not authenticate the customer and does not grant access to protected app data. The customer enters a license. Before submitting it, the SDK obtains a challenge using the installation's public key. It signs the challenge with the private key kept on that installation. AuthlyX checks the license, application rules, expiry and device limits before issuing an authenticated session. ```mermaid flowchart TD A[Customer opens MyApp] --> B[Initialize using AppKey and app version] B --> C[Receive app settings and release information] C --> D[Customer chooses an enabled sign-in method] D --> L[License: submit the customer's key] D --> U[Username: submit username and password] D --> V[Device: submit the configured whitelisted identifier] L --> P[SDK obtains a challenge and signs installation proof] U --> P V --> P P --> Q{Does the identity pass access and app-policy checks?} Q -->|No| X[Return a rejection; do not issue an authenticated session] Q -->|Yes| S[Create server session tied to app, identity and installation] S --> T[Return token, session ID, identity data and access deadline] T --> R[MyApp requests a variable, script, feature or other protected data] R --> SIGN[SDK attaches token and signs the exact request] SIGN --> CHECK[Server validates session, proof and current access rules] CHECK --> DATA[Return requested data when allowed] T --> H[Heartbeat runs at the configured interval] H --> VALID{Session still valid?} VALID -->|Yes| EXT[Return renewed access deadline] EXT --> H VALID -->|Revoked or expired| LOCK[Stop protected actions and show the reason] VALID -->|Network failure| OFF[Consider existing valid offline permission] T --> OUT[Customer signs out] OUT --> END[Revoke online session and clear local access] ``` ## What the session contains The server associates the session with the application, authenticated user/license/device, installation public key, device identifier, app version and expiry. A session ID identifies that record. The bearer token authorizes protected requests together with the installation proof; a session ID alone is not a replacement for these credentials. The SDK stores the active session in its client instance. It adds the token and request proof when you read cloud variables, fetch scripts, read public metadata, send logs or use other protected endpoints. Direct HTTP clients must send the same documented authentication and signing fields themselves. ## Why check again after login? A customer can sign in at 9:00 and have their license paused at 9:05. Keeping the original login result forever would miss that change. A session check asks the server whether the linked identity, application and device are still allowed. Use server heartbeat mode for automatic checks, or manual mode when your application schedules them. The server provides the interval; the configured fallback is ten minutes. An interval and an access deadline are different: permission is bounded by the deadline, not by a promise that the next network request will succeed. ## When access ends For a definitive ban, pause, expiry or ended session, stop protected actions and show a clear message. Keep unsaved work available where possible. The SDK must not terminate the process or choose a new screen for you. Your application decides whether to return to login or show a locked screen. A timeout does not prove a ban. Handle connection failures separately and use offline access only when a valid permit allows it. After sleep or resume, recheck the session before resuming protected work. Logout ends the online session and clears local access state. ## Test it Sign in with a test license, check the session, then end it in the dashboard. Check again from the same running app. The old token must be rejected. Repeat with a paused license and with a network outage; those cases should produce different decisions. See the SDK Check session page for language-specific calls and the Client API Sessions reference for direct requests. # Documentation: software-licensing A software license is a record of permission to use your product. The license key is the value your customer presents so your app can find and check that permission. The key itself is not the plan, expiry or device limit: those details are stored with the license on the server. ## Follow a license for MyApp You sell a 30-day Professional license for MyApp. In the dashboard, you create the license, choose Professional, set its duration and allow two devices. You send the key to the customer. The value could be generated, or it could be your own custom string such as `ADE`. ```mermaid flowchart TD A[You create a license for MyApp] --> B[Choose plan, expiry and device limit] B --> C[Give the customer its license value] C --> D[Customer enters the key in MyApp] D --> E[MyApp submits license login with installation proof] E --> F[AuthlyX finds that key inside the correct application] F --> G{Active, unexpired and within device and app rules?} G -->|Yes| H[Return authenticated session and customer access data] H --> I[MyApp enables the allowed operations] I --> J[Session checks continue during use] G -->|No| K[Return a code and explanation; do not grant access] J --> L[Expiry, pause, ban or ended session stops protected access] ``` ## What the plan does Professional can provide defaults such as PDF export enabled and 4K previews. The license still has its own expiry, device bindings and individual overrides. Your app reads the effective values after login. Assigning a plan name alone does not automatically implement paid features in your code. ## Expiry and first use You can use a specific expiry date or, where configured, begin a duration on the first successful login. A 30-day duration that starts on first login should not lose days while the unused key sits in a customer's inbox. A fixed expiry date is different: access ends at that date even if the customer starts late. Read the actual expiry returned by the server instead of calculating a fresh 30 days at every launch. A successful login today does not promise access forever. Check the active session and respond to changes. ## Remembering a key A Remember me option belongs to your application's interface. It can save a key or another supported protected state so the customer does not type it every time. Saving the value does not extend access and should not bypass server checks. Do not store customer credentials in a public or unprotected file. ## Licenses and usernames License login can be the only method you offer, or it can sit beside username and password and device login. Some products let the customer register a username using a license; others keep all access directly on license records. Check the registration behaviour before designing that flow. ## What licensing can and cannot protect Licensing makes access manageable: you can issue permission, set its term and revoke it. A customer can still inspect and modify software running on their own machine. Keep valuable server operations protected on your backend, verify signed responses, and make your program actually enforce rejection results. Use a test license before issuing a batch. Test the right key, a wrong key, expiry, pause, ban, the device limit and session revocation. Include an outage test so a connection problem is handled differently from an explicit access rejection. # Documentation: supported-platforms Your app calls the same V3 service whether it is written in C#, C++ or Python. The SDK handles the request format and verifies replies. Its runtime requirements still depend on the language. ## Start with a supported runtime | SDK | Current target | | --- | --- | | C# | .NET Framework 4.8 and .NET 8; a .NET Standard 2.0 library target is also available | | C++ | C++20 with the dependencies included in its build instructions | | Python | Python 3.11 or newer | | JavaScript and TypeScript | Node.js 22 or newer; these are not browser SDKs | | Java | Java 17 or newer | | Go | Go 1.23 or newer | | Rust | Rust 1.88 or newer, with Tokio | A language being supported does not mean every framework or platform has been tested. In particular, test device identifiers, protected storage and application shutdown on the operating system you actually ship. The default Windows identifier is not automatically a suitable identifier for Linux, macOS or a mobile device. ## Console and desktop interfaces A console can wait for a result during startup. A WinForms, WPF or game UI must keep its main thread responsive while a request is in progress. Use the callback or asynchronous integration documented for that SDK. Return to your UI thread before updating controls if the framework requires it. AuthlyX does not choose your login screen, open your dashboard window or kill the process after access ends. Your application handles those decisions. See Sessions and heartbeats for the access lifecycle. ## Framework packages Unity, Unreal Engine and other framework-specific entries may appear in the SDK catalog. An entry marked Coming soon is not a released integration. Do not assume a desktop C# or C++ example will run unchanged inside a game engine. Use the SDKs tab for downloads, dependencies and exact method examples. That section is the source for language syntax; these guides explain the product behaviour without repeating every language sample. # Documentation: test-integration Test a rejected login as carefully as a successful one. Your app should explain the problem and keep protected actions unavailable. ## Run these checks | Try this | What to check | | --- | --- | | Sign in with a valid test identity | Your app opens the intended features and shows the correct user data | | Enter the wrong password or key | The app stays signed out and displays the returned reason | | Ban the identity after login | A session check rejects access and your app responds appropriately | | End the session from the dashboard | The old session cannot keep making protected requests | | Disconnect the network | The app remains responsive and follows its access deadline/offline policy | | Sign out, then sign in as someone else | The previous customer's data and access are cleared | ## Check the result, not the message text Use the success indicator and stable response code for your application's decisions. Display the message to the customer. Messages can be customized, so comparing an English sentence is not a reliable access check. ## Keep the interface responsive While a request is waiting, try typing and moving the window. Avoid blocking the UI thread to wait for a result. Follow your language's SDK examples for callbacks or asynchronous calls, and update controls on the UI thread where your framework requires it. ## Check the version you distribute Test the built application and the SDK package you will ship, not only the source in your editor. Verify the API address, AppKey, version and verification-key configuration. Remove test credentials from screenshots and logs. Use SDK methods for language examples and API Reference for direct HTTP integrations. # Documentation: updates Open **Updates** in your app's sidebar. Each channel has its own latest version, download link and release notes. | Channel | Latest version | Download link | | --- | --- | --- | | Stable | 1.4.0 | https://example.com/ger-1.4.0.zip | | Beta | 1.5.0-beta.2 | https://example.com/ger-beta.zip | ## Set up your releases 1. Open Stable and enter the version and download link you want most customers to use. 2. Add Beta if you want a separate test release. Enter its version and download link. 3. Open the Settings tab and turn on **Check for updates**. 4. Choose the default channel for new identities. Existing assignments stay unchanged. Your previous automatic-update link is kept in Stable. Stable cannot be deleted. ## Choose who gets Beta Open a user, license or standalone device and choose its **Release channel**. Select several records and use **Change channel** to update them together. A plan can set a default channel for new identities. Changing the plan default does not move identities you already created. A linked username and license share one assignment; device activations use their user's or license's assignment. ## What the API returns Initialization has no signed-in identity, so it returns `update.requiresLogin: true` without a personal download link. The login response and successful session checks return the assigned release under `data.update`, with `channel`, `channelName`, `version`, `url` and `notes`. `data.updateAvailable` tells the client whether a newer release is offered. Changing a channel does not install anything. Semantic version comparisons avoid offering an older release as a new update. Use versions such as `1.4.0` and `1.5.0-beta.2`; custom version labels are compared as different labels. ## Allowed Versions is separate Allowed Versions controls which builds may connect. Channels control which update a customer receives. Assigning Beta does not stop that customer running an allowed Stable version. A verified sign-in blocked by Allowed Versions returns `UPDATE_REQUIRED` with the assigned update details, without issuing a session. An existing session blocked by a version change receives update details too. ## Download links A MediaFire page should open in the browser. A direct ZIP or installer link can also be opened in the browser. AuthlyX currently provides release information; it does not silently install files or close the customer's application. SDK-specific update screens and download helpers are a separate integration step. Direct API users can read the fields above immediately. # Documentation: v1-connect ## Copy your application details Use the details of the same application that contains your licenses and users. Keep the existing owner ID unchanged when moving an account. ## Initialize Send `POST /api/v1/init` with the four connection fields: ```json { "owner_id": "459010927960", "app_name": "MyApp", "version": "1.0.0", "secret": "YOUR_APPLICATION_SECRET" } ``` The secret above is a placeholder: paste your own application's secret when testing privately. Never put an Elite Key here. Initialization returns the legacy session information. Keep that session in memory and use it for the next request. Initialization alone does not sign in a customer. ## Choose how the customer signs in | Access | Route | Credentials | | --- | --- | --- | | Username | `/api/v1/login` | Username, password and system ID | | License | `/api/v1/licenses` | License key and system ID | | Device | `/api/v1/device-auth` | Device type and device ID | Use the API Reference for the complete request fields, including `session_id`. Do not add V3 challenge headers to these requests. ## Keep checking access Call `/api/v1/validate-session` while protected features are in use. A successful sign-in is not a permanent approval. A developer can later pause, ban or expire access. If access is rejected, stop protected operations and let the customer sign in again. A connection failure is different from a server response that says the license is banned. # Documentation: v1-overview V1 is no longer maintained. These docs remain available for existing integrations. End of support does not mean a running V1 API has been switched off. This section is for software already using AuthlyX V1. It keeps the old connection details, request names and responses together. New integrations should use V3. ## What you need An AuthlyX application, its owner ID, app name, version and secret. These are the four values the old SDK expects. Do not replace them with a V3 AppKey in an existing build. ## Where to go - **Get Started:** connect your application and test access. - **SDKs:** understand the legacy SDK contract and read results. - **API Reference:** request fields and responses for `/api/v1/`. The rebuilt API includes compatibility routes for this version. They are tested locally; that does not mean your deployed host has been upgraded. Keep the URL in your existing release until the production migration is complete. V1 is archived. Continued compatibility does not restore support or add V3 features to it. Chat is discontinued. Historical chat routes in this archived reference are not available in the rebuilt service. # Documentation: v1-results Initialize first, keep the returned session ID, then call the appropriate sign-in endpoint. Check the success field and message documented for that endpoint before allowing protected actions. Each response belongs to one request. A successful initialization does not mean the customer's license has been accepted. Read the sign-in response separately. When calling the API yourself, handle both an HTTP failure and a valid JSON response that rejects access. A timeout is not a successful response and should not be shown as a ban without a server decision. No V1 SDK method names are invented here. Use the source distributed with your existing V1 application or the endpoint examples in API Reference. # Documentation: v1-sdks V1 is an archived HTTP contract. The available old example projects target V2; relabelling those projects as V1 would give you the wrong security and response contract. Keep the exact V1 SDK source and dependencies already shipped with your application. If you call HTTP directly, use the V1 API Reference. There is no separately verified V1 SDK download in this documentation yet. Do not replace your V1 source with a V2 or V3 download without changing and testing the integration. V3 uses an AppKey and installation proof; V1 uses owner ID, app name, version and secret. # Documentation: v1-testing Use a separate test application. Keep real customer licenses out of screenshots and logs. 1. Initialize with the correct app details. Repeat with an incorrect secret and confirm access is refused. 2. Sign in with a test license, a username and an approved device separately. 3. Try a wrong password and a nonexistent key. Neither should open protected features. 4. Validate the active session. Then pause the identity in the dashboard and validate again: access must stop. 5. Repeat with a ban and an expired identity. 6. Fill the device limit, then try another device. Reset one device and confirm the replacement can connect. 7. Read a variable, change its value in the dashboard and read it again. Try updating a read-only variable remotely and confirm rejection. 8. Try using the session with a different application's data. It must not grant access. 9. Disconnect the network. Your interface should show the connection failure without treating it as a successful login. For migration, repeat these checks with the unchanged old client against the local compatibility API before changing the production host. Keep a database backup and the previous deployment available for rollback. # Documentation: v2-connect ## Copy your application details Use the details of the same application that contains your licenses and users. Keep the existing owner ID unchanged when moving an account. ## Initialize Send `POST /api/v2/init` with the four connection fields: ```json { "owner_id": "459010927960", "app_name": "MyApp", "version": "1.0.0", "secret": "YOUR_APPLICATION_SECRET" } ``` The secret above is a placeholder: paste your own application's secret when testing privately. Never put an Elite Key here. Initialization returns the legacy session information. Keep that session in memory and use it for the next request. Initialization alone does not sign in a customer. ## Choose how the customer signs in | Access | Route | Credentials | | --- | --- | --- | | Username | `/api/v2/login` | Username, password and system ID | | License | `/api/v2/licenses` | License key and system ID | | Device | `/api/v2/device-auth` | Device type and device ID | Use the API Reference for the complete request fields, including `session_id`. Do not add V3 challenge headers to these requests. ## Keep checking access Call `/api/v2/validate-session` while protected features are in use. A successful sign-in is not a permanent approval. A developer can later pause, ban or expire access. If access is rejected, stop protected operations and let the customer sign in again. A connection failure is different from a server response that says the license is banned. # Documentation: v2-overview V2 is the legacy version for existing integrations. Use V3 for new projects. This section is for software already using AuthlyX V2. It keeps the old connection details, request names and responses together. New integrations should use V3. ## What you need An AuthlyX application, its owner ID, app name, version and secret. These are the four values the old SDK expects. Do not replace them with a V3 AppKey in an existing build. ## Where to go - **Get Started:** connect your application and test access. - **SDKs:** understand the legacy SDK contract and read results. - **API Reference:** request fields and responses for `/api/v2/`. The rebuilt API includes compatibility routes for this version. They are tested locally; that does not mean your deployed host has been upgraded. Keep the URL in your existing release until the production migration is complete. V2 remains the legacy contract. V3 installation signatures, offline permits and release-channel behaviour must not be assumed to exist in a V2 SDK. Chat is discontinued. Historical chat routes in this archived reference are not available in the rebuilt service. # Documentation: v2-results ## Initialize and read the result This is the old C# contract, not the V3 callback contract: ```csharp app.Init(); if (app.response.success) { Console.WriteLine("Connected"); } else { Console.WriteLine(app.response.message); } ``` ## Sign in ```csharp app.Login(username, password); if (app.response.success) { Console.WriteLine("Signed in"); } else { Console.WriteLine(app.response.message); } ``` `username` and `password` are strings from your own form or console input. Read the response immediately after the operation: the next operation replaces the shared response. The synchronous calls wait for the network. Use the callback overload on a desktop UI instead of blocking its UI thread. Do not run overlapping operations against the legacy shared response. For direct HTTP calls, use each endpoint's documented response. Do not expect V3's `result.ok` or installation proof fields in a V2 response. # Documentation: v2-sdks The existing source examples use the V2 API. Keep each SDK's original dependencies and verification code with that source. V3 SDK downloads are not drop-in replacements. The C# example uses namespace `AuthlyX` and class `Auth`. Its methods use PascalCase, such as `Init`, `Login`, `Register`, `GetVariable` and `ValidateSession`. ```csharp public static Auth app = new Auth( ownerId: "459010927960", appName: "MyApp", version: "1.0.0", secret: "YOUR_APPLICATION_SECRET" ); ``` For a custom V2 host, use the SDK's `api` option with the complete V2 base URL. Do not point it at `/v3`. The legacy examples include C#, C++, Python, JavaScript, TypeScript, Java, Go and Rust sources. Runtime requirements belong to each original project's dependency and build files; they are not the V3 compatibility table. Separate archived downloads are not yet packaged here. # Documentation: v2-testing Use a separate test application. Keep real customer licenses out of screenshots and logs. 1. Initialize with the correct app details. Repeat with an incorrect secret and confirm access is refused. 2. Sign in with a test license, a username and an approved device separately. 3. Try a wrong password and a nonexistent key. Neither should open protected features. 4. Validate the active session. Then pause the identity in the dashboard and validate again: access must stop. 5. Repeat with a ban and an expired identity. 6. Fill the device limit, then try another device. Reset one device and confirm the replacement can connect. 7. Read a variable, change its value in the dashboard and read it again. Try updating a read-only variable remotely and confirm rejection. 8. Try using the session with a different application's data. It must not grant access. 9. Disconnect the network. Your interface should show the connection failure without treating it as a successful login. For migration, repeat these checks with the unchanged old client against the local compatibility API before changing the production host. Keep a database backup and the previous deployment available for rollback. # Documentation: webhooks Suppose a customer buys a license and your own order system needs to mark it as delivered. Add a webhook destination for your server and select `license.created`. When AuthlyX creates a license, it sends a signed request to that URL. Your server can record the event without polling AuthlyX every minute. ```mermaid %%{init: {"theme":"base","themeVariables":{"primaryColor":"#ffffff","primaryTextColor":"#171717","primaryBorderColor":"#404040","lineColor":"#606060","secondaryColor":"#f5f5f5","tertiaryColor":"#ffffff","edgeLabelBackground":"#ffffff"}}}%% sequenceDiagram participant A as AuthlyX dashboard or API participant Q as AuthlyX delivery queue participant S as Your server A->>Q: license.created Q->>S: Signed HTTPS request S->>S: Verify signature and check event ID S-->>Q: 2xx after accepting event ``` ## Add a destination 1. Open **Webhooks** for the app and add a destination name, such as `Northstar Orders`. 2. Enter an HTTPS URL on your server. 3. Create and save a signing secret. Keep it on your server; AuthlyX does not need to show it again after setup. 4. Choose only the events your server needs. For example, use `license.created`, `identity.paused` and `plan.updated` if you synchronize license delivery and plan changes. 5. Send a test delivery. Check its status and response under **Deliveries**. One app can have several destinations. For example, send license events to your order system and audit events to a separate monitoring service. Each destination has its own URL, secret and event list. ## Verify before acting Treat every webhook request as untrusted until its signature passes. Read the exact raw request body, then calculate HMAC-SHA256 using that destination's secret over `timestamp + "." + rawBody`. Compare the result with the `v1=...` value in `X-AuthlyX-Signature`, and check that `X-AuthlyX-Timestamp` is recent. Verify the signature before parsing and using the event fields. Save each event ID before processing it. AuthlyX retries temporary delivery failures, so the same event can arrive more than once. If your server already processed that event ID, return a 2xx response without repeating the action. ## If your server is down Return a non-2xx response when your server has not safely accepted the event. AuthlyX records the attempt and retries temporary failures. Use the Deliveries page to see status, response code and attempts, then retry where available. Webhooks are useful for synchronizing your own services. They do not replace a live access check when a customer signs in. The SDK should still ask AuthlyX whether the license, user or device may access the app. # Complete V1 API specification ```json { "openapi": "3.0.3", "info": { "title": "AuthlyX V1 - End of Support", "version": "1.0.0", "description": "Archived V1 SDK API. No new integrations should use this version. These paths are retained as historical reference; this is not a shutdown announcement." }, "servers": [ { "url": "https://authly.cc", "description": "Existing production host" }, { "url": "https://api.authlyx.dev", "description": "New API host - deployment pending" }, { "url": "http://127.0.0.1:4000", "description": "Local compatibility API" } ], "paths": { "/api/v1/init": { "post": { "operationId": "v1_init", "summary": "Init", "deprecated": true, "description": "Archived request fields from the V1 init handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string" }, "app_name": { "type": "string" }, "version": { "type": "string" }, "secret": { "type": "string" }, "hash": { "type": "string" }, "ip": { "type": "string" } } }, "example": { "owner_id": "459010927960", "app_name": "MyApp", "version": "1.0.0", "secret": "b7f8c2e46a9130d5b7f8c2e46a9130d5b7f8c2e46a9130d5b7f8c2e46a9130d5", "hash": "a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f", "ip": "197.210.54.18" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/login": { "post": { "operationId": "v1_login", "summary": "Login", "deprecated": true, "description": "Archived request fields from the V1 login handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "sid": { "type": "string" }, "hwid": { "type": "string" }, "ip": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "username": "alex", "password": "River-Glass-29", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/register": { "post": { "operationId": "v1_register", "summary": "Register", "deprecated": true, "description": "Archived request fields from the V1 register handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "email": { "type": "string" }, "key": { "type": "string" }, "sid": { "type": "string" }, "hwid": { "type": "string" }, "ip": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "username": "alex", "password": "River-Glass-29", "email": "alex@example.com", "key": "preferredLanguage", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/licenses": { "post": { "operationId": "v1_licenses", "summary": "Licenses", "deprecated": true, "description": "Archived request fields from the V1 licenses handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "license_key": { "type": "string" }, "sid": { "type": "string" }, "hwid": { "type": "string" }, "ip": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "license_key": "MyApp", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/licenses/verify": { "post": { "operationId": "v1_licenses_verify", "summary": "Licenses verify", "deprecated": true, "description": "Archived request fields from the V1 verifyLicense handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "license_key": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "license_key": "MyApp" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/extend": { "post": { "operationId": "v1_extend", "summary": "Extend", "deprecated": true, "description": "Archived request fields from the V1 extend handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "username": { "type": "string" }, "license_key": { "type": "string" }, "sid": { "type": "string" }, "hwid": { "type": "string" }, "ip": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "username": "alex", "license_key": "MyApp", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/variables": { "post": { "operationId": "v1_variables", "summary": "Variables", "deprecated": true, "description": "Archived request fields from the V1 variables handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "var_key": { "type": "string" }, "var_value": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "var_key": "MyApp", "var_value": "MyApp" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/variables/set": { "post": { "operationId": "v1_variables_set", "summary": "Variables set", "deprecated": true, "description": "Archived request fields from the V1 variables handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "var_key": { "type": "string" }, "var_value": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "var_key": "MyApp", "var_value": "MyApp" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/logs": { "post": { "operationId": "v1_logs", "summary": "Logs", "deprecated": true, "description": "Archived request fields from the V1 logs handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "message": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "message": "License verified. Application started." } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/validate-session": { "post": { "operationId": "v1_validate_session", "summary": "Validate session", "deprecated": true, "description": "Archived request fields from the V1 validateSession handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/chats/send": { "post": { "operationId": "v1_chats_send", "summary": "Chats send", "deprecated": true, "description": "Archived request fields from the V1 chats handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "channel_name": { "type": "string" }, "message": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "channel_name": "MyApp", "message": "License verified. Application started." } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/chats/get": { "post": { "operationId": "v1_chats_get", "summary": "Chats get", "deprecated": true, "description": "Archived request fields from the V1 chats handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "channel_name": { "type": "string" }, "message": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "channel_name": "MyApp", "message": "License verified. Application started." } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/device-auth": { "post": { "operationId": "v1_device_auth", "summary": "Device auth", "deprecated": true, "description": "Archived request fields from the V1 device-auth handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "device_type": { "type": "string" }, "device_id": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "device_type": "MyApp", "device_id": "MyApp" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } }, "/api/v1/change-password": { "post": { "operationId": "v1_change_password", "summary": "Change password", "deprecated": true, "description": "Archived request fields from the V1 change-password handler. Consult your matching V1 SDK for field requirements and historical response handling.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "old_password": { "type": "string" }, "new_password": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "old_password": "MyApp", "new_password": "MyApp" } } } }, "responses": { "200": { "description": "V1 response. Check success and code; HTTP success alone is not authorization." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid session or credentials." }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit reached." } } } } } } ``` # Complete V2 API specification ```json { "openapi": "3.1.0", "info": { "title": "AuthlyX V2 - Legacy", "version": "2.0", "description": "Legacy V2 API for existing integrations. Do not use this specification for V3.\n\nLegacy public API v2 reference, imported from the existing AuthlyX documentation. This does not describe the isolated rebuild API on port 4000. Review against the deployed API before publishing.\n\nAuthlyX is a software licensing and authentication API.\n\n**Flow:** Every client session starts with a call to `POST /api/v2/init`.\nA successful Init returns a `session_id` that must be passed to every\nsubsequent endpoint. Sessions expire after 24 hours - re-init to get a new one.\n\nThe Elite Key API (`/api/elite-key`) is a separate server-side management\nAPI and does not use the session flow.\n", "contact": { "name": "AuthlyX", "url": "https://authly.cc" }, "license": { "name": "Proprietary", "url": "https://authly.cc" } }, "security": [], "servers": [ { "url": "https://authly.cc", "description": "Existing production host" }, { "url": "https://api.authlyx.dev", "description": "New API host - deployment pending" }, { "url": "http://127.0.0.1:4000", "description": "Local compatibility API" } ], "tags": [ { "name": "Session", "description": "Initialize and validate client sessions." }, { "name": "Auth", "description": "User authentication - login, register, extend, change password." }, { "name": "Device", "description": "Hardware device authentication." }, { "name": "Utilities", "description": "Variables, logs, and chat channels." }, { "name": "Elite Key", "description": "Server-side management API for licenses, users, and app settings." } ], "components": { "schemas": { "ErrorResponse": { "type": "object", "required": [ "success", "code", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "string", "example": "MISSING_FIELDS" }, "message": { "type": "string", "example": "Required fields are missing" } } }, "SessionBody": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "description": "Active session ID from a successful Init call.", "example": "dc1cea3a75" } } } }, "responses": { "400Missing": { "description": "Missing or invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } }, "401Session": { "description": "Session invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid": { "value": { "success": false, "code": "INVALID_SESSION", "message": "Invalid session" } }, "expired": { "value": { "success": false, "code": "SESSION_EXPIRED", "message": "Session has expired" } } } } } }, "500Internal": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "code": "INTERNAL", "message": "An internal server error occurred" } } } } } }, "paths": { "/api/v2/init": { "post": { "operationId": "init", "summary": "Initialize a session", "description": "The first call every client must make. Verifies owner credentials,\nruns IP/VPN/country checks, validates the optional executable hash,\nchecks the app version, and returns a `session_id` valid for 24 hours.\nAll other v2 endpoints require this session_id.\n", "tags": [ "Session" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "owner_id", "app_name", "secret", "version" ], "properties": { "owner_id": { "type": "string", "description": "Developer ID from the AuthlyX dashboard.", "example": "12345678" }, "app_name": { "type": "string", "description": "Exact registered app name (case-sensitive).", "example": "MyApp" }, "secret": { "type": "string", "description": "App secret key. Never expose client-side.", "example": "your-secret-key" }, "version": { "type": "string", "description": "Client version string used for version control enforcement.", "example": "1.3" }, "hash": { "type": "string", "description": "SHA-256 hash of the compiled executable. Required only if hash checking is enabled.", "example": "a3f5c9..." } } }, "example": { "owner_id": "12345678", "app_name": "MyApp", "secret": "your-secret-key", "version": "1.3", "hash": "a3f5c9..." } } } }, "responses": { "200": { "description": "Session created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Init success" }, "session_id": { "type": "string", "example": "a3f5c9d2e1b4..." }, "owner_id": { "type": "string", "example": "12345678" }, "app_name": { "type": "string", "example": "MyApp" }, "version": { "type": "string", "example": "1.3" }, "update": { "type": "object", "description": "Present when version control triggers a reminder or grace period.", "properties": { "latest_version": { "type": "string" }, "auto_update_enabled": { "type": "boolean" }, "force_update": { "type": "boolean" }, "download_url": { "type": [ "string", "null" ] } } } } }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "message": "Init success", "session_id": "a3f5c9d2e1b4...", "owner_id": "12345678", "app_name": "MyApp", "version": "1.3", "update": { "latest_version": "MyApp", "auto_update_enabled": true, "force_update": true, "download_url": "https://downloads.example.com/ger/1.4.1.zip" } } } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "description": "Invalid owner or secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "403": { "description": "Access blocked by IP, VPN, country, or app status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "426": { "description": "Version mismatch or update required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Request failed": { "summary": "Request failed", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "owner_id": "12345678", "app_name": "MyApp", "secret": "your-secret-key", "version": "1.3", "hash": "a3f5c9..." }, "response": { "body": { "success": true, "message": "Init success", "session_id": "a3f5c9d2e1b4...", "owner_id": "12345678", "app_name": "MyApp", "version": "1.3", "update": { "latest_version": "MyApp", "auto_update_enabled": true, "force_update": true, "download_url": "https://downloads.example.com/ger/1.4.1.zip" } } } } ] } }, "/api/v2/validate-session": { "post": { "operationId": "validateSession", "summary": "Validate a session", "description": "Checks whether a session is still active and not expired.", "tags": [ "Session" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionBody" }, "example": { "session_id": "dc1cea3a75" } } } }, "responses": { "200": { "description": "Session is valid.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/login": { "post": { "operationId": "login", "summary": "Authenticate a user", "description": "Authenticates a user with username and password against an active session.\nEnforces device limits, IP rules, and account status checks.\nReturns a refreshed session_id and full user details on success.\n", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "username", "password", "sid" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "username": { "type": "string", "example": "xela" }, "password": { "type": "string", "example": "hunter2" }, "sid": { "type": "string", "description": "System/HWID identifier. Enforces device limits and locks the session to this machine.", "example": "S-1-5-21-...." }, "ip": { "type": "string", "description": "Client IP address. Inferred from request headers if omitted.", "example": "102.88.xxx.xxx" } } }, "example": { "session_id": "dc1cea3a75", "username": "xela", "password": "hunter2", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" } } } }, "responses": { "200": { "description": "Login successful.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "description": "Session or credential check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "403": { "description": "Access blocked by security policy or account status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "User not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "username": "xela", "password": "hunter2", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/licenses": { "post": { "operationId": "licenseLogin", "summary": "Authenticate a license key", "description": "Authenticates a license key against an active session. Use this when\nyour app distributes license keys rather than user accounts.\nEnforces device limits and, on success, registers the device and\nupdates the session and license's `sid`/`ip_address`/`last_login`.\nFor a read-only status check that does not touch device or session\nstate, use `POST /api/v2/licenses/verify` instead.\n", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "license_key", "sid" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "license_key": { "type": "string", "description": "The license key to authenticate.", "example": "XXXXX-XXXXX-XXXXX-XXXXX" }, "sid": { "type": "string", "description": "Unique system identifier (or hwid). Enforces device limits and locks the session to this machine.", "example": "S-1-5-21-...." }, "ip": { "type": "string", "description": "Client IP address. Inferred from request headers if omitted.", "example": "102.88.xxx.xxx" } } }, "example": { "session_id": "dc1cea3a75", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" } } } }, "responses": { "200": { "description": "Login successful. Returns license details and a refreshed session.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "Access blocked by license status or device policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "License key not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/licenses/verify": { "post": { "operationId": "verifyLicense", "summary": "Verify a license's status", "description": "Read-only license status check: exists, not banned, not paused, not\nexpired. Unlike `POST /api/v2/licenses`, this does not register a\ndevice, does not enforce `max_devices`, and does not update\n`sid`/`ip_address`/`last_login` on the license or the session.\nIntended for periodic background re-checks of an already-activated\nlicense.\n", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "license_key" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "license_key": { "type": "string", "description": "The license key to check.", "example": "XXXXX-XXXXX-XXXXX-XXXXX" } } }, "example": { "session_id": "dc1cea3a75", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX" } } } }, "responses": { "200": { "description": "License is valid. Returns license details; no device, session, or usage state is modified.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "License is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "License key not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/register": { "post": { "operationId": "register", "summary": "Register a new user", "description": "Creates a new user account by redeeming an unused license key.\nReturns a new session_id and user details on success.\nThe license key is consumed on successful registration.\n", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "username", "password", "key" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "username": { "type": "string", "example": "xela" }, "password": { "type": "string", "example": "hunter2" }, "key": { "type": "string", "description": "Unused license key. Consumed on successful registration.", "example": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX" }, "email": { "type": "string", "example": "user@example.com" }, "sid": { "type": "string", "description": "System identifier to bind the device on registration.", "example": "S-1-5-21-...." } } }, "example": { "session_id": "dc1cea3a75", "username": "xela", "password": "hunter2", "key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX", "email": "user@example.com", "sid": "S-1-5-21-...." } } } }, "responses": { "201": { "description": "Account created successfully.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "License blocked or not eligible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "License key not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "409": { "description": "Username already taken.", "content": { "application/json": { "examples": { "Request failed": { "summary": "Request failed", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } } } }, "/api/v2/extend": { "post": { "operationId": "extend", "summary": "Extend a user's subscription", "description": "Extends a user's subscription by redeeming an unused license key.\nThe key's duration is added on top of the current expiry date.\nIf the user is already expired, the extension starts from today.\n", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "username", "license_key", "sid" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "username": { "type": "string", "example": "xela" }, "license_key": { "type": "string", "description": "Unused license key whose duration will be applied.", "example": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX" }, "sid": { "type": "string", "description": "System identifier for security consistency check.", "example": "S-1-5-21-...." }, "ip": { "type": "string", "example": "102.88.xxx.xxx" } } }, "example": { "session_id": "dc1cea3a75", "username": "xela", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" } } } }, "responses": { "200": { "description": "Extension successful.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "description": "Missing fields or invalid duration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "User or license blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "User or license not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "username": "xela", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/change-password": { "post": { "operationId": "changePassword", "summary": "Change user password", "description": "Changes the password of the user linked to the active session.", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "old_password", "new_password" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "old_password": { "type": "string", "example": "old" }, "new_password": { "type": "string", "example": "new" } } }, "example": { "session_id": "dc1cea3a75", "old_password": "old", "new_password": "new" } } } }, "responses": { "200": { "description": "Password changed successfully.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "description": "Missing fields or password reused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "401": { "description": "Session or password check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "403": { "description": "Password change disabled or user blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "User not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "old_password": "old", "new_password": "new" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/device-auth": { "post": { "operationId": "deviceAuth", "summary": "Authenticate a device", "description": "Authenticates a hardware device (motherboard or processor) against the\nactive session. Returns device subscription details on success.\n", "tags": [ "Device" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "device_type", "device_id" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "device_type": { "type": "string", "enum": [ "motherboard", "processor" ], "example": "motherboard" }, "device_id": { "type": "string", "description": "Unique hardware identifier string extracted from the client machine.", "example": "PDPCF001X4YJ2Q" } } }, "example": { "session_id": "dc1cea3a75", "device_type": "motherboard", "device_id": "PDPCF001X4YJ2Q" } } } }, "responses": { "200": { "description": "Device authenticated.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "description": "Missing fields or invalid device type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "Device banned, paused, or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "Device not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "device_type": "motherboard", "device_id": "PDPCF001X4YJ2Q" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/variables": { "post": { "operationId": "getVariable", "summary": "Get a cloud variable", "description": "Retrieves the value of a cloud variable for the current app.", "tags": [ "Utilities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "var_key" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "var_key": { "type": "string", "description": "Key identifier of the cloud variable to retrieve.", "example": "my_variable" } } }, "example": { "session_id": "dc1cea3a75", "var_key": "my_variable" } } } }, "responses": { "200": { "description": "Variable retrieved.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "404": { "description": "Variable not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "var_key": "my_variable" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/variables/set": { "post": { "operationId": "setVariable", "summary": "Set a cloud variable", "description": "Creates or updates a cloud variable for the current app.", "tags": [ "Utilities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "var_key", "var_value" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "var_key": { "type": "string", "example": "my_variable" }, "var_value": { "type": "string", "description": "String value to write to the variable.", "example": "hello" } } }, "example": { "session_id": "dc1cea3a75", "var_key": "my_variable", "var_value": "hello" } } } }, "responses": { "200": { "description": "Variable updated.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "404": { "description": "Variable key not found in app settings.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "var_key": "my_variable", "var_value": "hello" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/logs": { "post": { "operationId": "sendLog", "summary": "Send a log message", "description": "Sends a log message from the client to be stored or forwarded to a\nconfigured webhook. If app logging is disabled, the endpoint still\nreturns 200 but does nothing.\n", "tags": [ "Utilities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "message" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "message": { "type": "string", "description": "Log text or data payload from the client.", "example": "Hello from the client" } } }, "example": { "session_id": "dc1cea3a75", "message": "Hello from the client" } } } }, "responses": { "200": { "description": "Log stored.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "Log quota exceeded.", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Forbidden", "value": "MyApp" } } } } }, "500": { "description": "Internal error or webhook delivery failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Request failed": { "summary": "Request failed", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "message": "Hello from the client" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/chats/send": { "post": { "operationId": "sendChatMessage", "summary": "Send a chat message", "description": "Broadcasts a message to the specified app chat channel.", "tags": [ "Utilities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "channel_name", "message" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "channel_name": { "type": "string", "example": "general" }, "message": { "type": "string", "example": "hello" } } }, "example": { "session_id": "dc1cea3a75", "channel_name": "general", "message": "hello" } } } }, "responses": { "200": { "description": "Message sent.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "User muted or not linked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "Channel not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "channel_name": "general", "message": "hello" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/chats/get": { "post": { "operationId": "getChatMessages", "summary": "Get chat messages", "description": "Retrieves messages from the specified app chat channel with pagination support.", "tags": [ "Utilities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "channel_name" ], "properties": { "session_id": { "type": "string", "example": "dc1cea3a75" }, "channel_name": { "type": "string", "example": "general" }, "limit": { "type": "integer", "default": 50, "description": "Maximum number of messages to return.", "example": 50 }, "cursor": { "type": [ "string", "null" ], "description": "Pagination cursor for older messages. Pass null for the first request.", "example": null } } }, "example": { "session_id": "dc1cea3a75", "channel_name": "general", "limit": 50, "cursor": null } } } }, "responses": { "200": { "description": "Messages retrieved.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "$ref": "#/components/responses/400Missing" }, "401": { "$ref": "#/components/responses/401Session" }, "403": { "description": "Access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "Channel not found.", "content": { "application/json": { "examples": { "Not found": { "summary": "Not found", "value": "MyApp" } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "dc1cea3a75", "channel_name": "general", "limit": 50, "cursor": null }, "response": { "body": "MyApp" } } ] } }, "/api/elite-key": { "get": { "operationId": "eliteKeyGet", "summary": "Execute an Elite Key action (GET)", "description": "Server-side management API. Requires the Elite plan.\nPass `function` + `action` to route the request to the correct module.\nAll parameters can also be sent as a form-urlencoded POST body.\n\n**Modules:** `license`, `user`, `device`, `variable`, `subscription`,\n`version`, `response`, `app`.\n\n**Security:** Never use from client code. Restrict usage with IP/domain\nwhitelists in Elite Key Settings. Reset immediately if the key leaks.\n", "tags": [ "Elite Key" ], "parameters": [ { "name": "key", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Your Elite Key from the dashboard." }, { "name": "function", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "license", "user", "device", "variable", "subscription", "version", "response", "app" ] } }, { "name": "action", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Operation to run. Available actions per function:\n- `license`: generate, edit, delete, extend, shorten, ban, unban, pause, unpause\n- `user`: generate, edit, delete, extend, shorten, ban, unban, pause, unpause, reset_password, verify_password\n- `device`: create, edit, delete, extend, ban, pause\n- `variable`: set, delete\n- `subscription`: create, edit, delete\n- `version`: add, edit, remove\n- `response`: set, reset\n- `app`: edit\n" }, { "name": "url_prefix", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Your app's URL prefix." }, { "name": "app_name", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Registered app name." } ], "responses": { "200": { "description": "Action completed.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "description": "Missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "401": { "description": "Elite Key invalid or inactive.", "content": { "application/json": { "examples": { "Unauthorized": { "summary": "Unauthorized", "value": "MyApp" } } } } }, "403": { "description": "Plan requirement, disabled action, or IP/domain restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "App, license, user, or subscription not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "response": { "body": "MyApp" } } ] }, "post": { "operationId": "eliteKeyPost", "summary": "Execute an Elite Key action (POST)", "description": "Server-side management API. Requires the Elite plan.\nPass `function` + `action` to route the request to the correct module.\nAll parameters can also be sent as a form-urlencoded POST body.\n\n**Modules:** `license`, `user`, `device`, `variable`, `subscription`,\n`version`, `response`, `app`.\n\n**Security:** Never use from client code. Restrict usage with IP/domain\nwhitelists in Elite Key Settings. Reset immediately if the key leaks.\n", "tags": [ "Elite Key" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "key", "function", "action", "url_prefix", "app_name" ], "properties": { "key": { "type": "string" }, "function": { "type": "string", "enum": [ "license", "user", "device", "variable", "subscription", "version", "response", "app" ] }, "action": { "type": "string" }, "url_prefix": { "type": "string" }, "app_name": { "type": "string" } } }, "example": { "key": "preferredLanguage", "function": "license", "action": "create", "url_prefix": "MyApp", "app_name": "MyApp" } } } }, "responses": { "200": { "description": "Action completed.", "content": { "application/json": { "examples": { "Successful": { "summary": "Successful", "value": "MyApp" } } } } }, "400": { "description": "Missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "401": { "description": "Elite Key invalid.", "content": { "application/json": { "examples": { "Unauthorized": { "summary": "Unauthorized", "value": "MyApp" } } } } }, "403": { "description": "Plan, permission, or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "MISSING_FIELDS", "message": "Required fields are missing" } } } } } }, "500": { "$ref": "#/components/responses/500Internal" } }, "x-fern-examples": [ { "name": "Successful", "request": { "key": "preferredLanguage", "function": "license", "action": "create", "url_prefix": "MyApp", "app_name": "MyApp" }, "response": { "body": "MyApp" } } ] } }, "/api/v2/blacklist/check": { "post": { "operationId": "v2BlacklistCheck", "summary": "Check blacklist", "tags": [ "Access policies" ], "description": "Legacy V2 check for a system ID or IP blacklist entry in the session application. The handler uses hwid first, then sid. If ip is omitted, it reads the connection/forwarded address. Uses V2 middleware and its deployed replay/signature configuration, not V3 request proof.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" }, "hwid": { "type": "string" }, "sid": { "type": "string" }, "ip": { "type": "string" } } }, "example": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" } } } }, "responses": { "200": { "description": "Blacklist result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "blacklisted": { "type": "boolean" } } }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "blacklisted": true } } } } } }, "400": { "description": "Missing session_id." }, "401": { "description": "Invalid or expired session." }, "429": { "description": "Rate limit reached." }, "500": { "description": "Internal server error." } }, "x-fern-examples": [ { "name": "Successful", "request": { "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" }, "response": { "body": { "success": true, "blacklisted": true } } } ] } } } } ``` # Complete V3 API specification ```json { "openapi": "3.0.3", "info": { "title": "AuthlyX Client API", "version": "3.0.0-beta", "description": "V3 beta runtime implemented in the AuthlyX rebuild. SDK requests use installation proof and signed server responses. The AppKey identifies an application; it is not a private management credential. Local testing uses port 4000. No production V3 deployment is implied by this specification." }, "servers": [ { "url": "http://127.0.0.1:4000", "description": "Local development" }, { "url": "https://api.authlyx.dev", "description": "Production host - deployment pending" } ], "components": { "securitySchemes": { "session": { "type": "http", "scheme": "bearer", "description": "Opaque v3 session token returned by login, bound to its identity and installation." } }, "schemas": { "SignedResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "nullable": true }, "requestId": { "type": "string", "format": "uuid" }, "verification": { "type": "object", "properties": { "keyId": { "type": "string" }, "signedPayload": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "keyId", "signedPayload", "signature" ] } }, "required": [ "success", "code", "message", "data", "requestId", "verification" ] }, "Initialization": { "type": "object", "properties": { "initialized": { "type": "boolean" }, "application": { "type": "string", "description": "App name." }, "version": { "type": "string", "description": "Requested version." }, "currentVersion": { "type": "string", "description": "Dashboard version." }, "updateAvailable": { "type": "boolean" }, "update": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "requiresLogin": { "type": "boolean" }, "channel": { "type": "string" }, "channelName": { "type": "string" }, "version": { "type": "string" }, "url": { "type": "string", "nullable": true }, "notes": { "type": "string" }, "mode": { "type": "string", "enum": [ "browser" ] } }, "required": [] } }, "required": [] }, "Challenge": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "payload": { "type": "string", "description": "Exact challenge JSON string to include in the installation proof." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "challengeId", "payload", "expiresAt" ] }, "CloudVariable": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] }, "ChatMessages": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "text": { "type": "string" }, "time": { "type": "string" } }, "required": [] } } }, "required": [ "messages" ] }, "SignedArtifact": { "type": "object", "properties": { "keyId": { "type": "string" }, "signedPayload": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "keyId", "signedPayload", "signature" ] }, "IdentityAccess": { "type": "object", "properties": { "features": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] } } }, "required": [ "features", "metadata" ] }, "Identity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "license", "device" ] }, "name": { "type": "string", "description": "Signed-in username, license or device identifier." }, "licenseKey": { "type": "string", "description": "License key or linked license, when applicable.", "nullable": true }, "email": { "type": "string", "description": "App-user email, if set.", "nullable": true }, "plan": { "type": "string", "description": "App plan name, not the developer billing plan.", "nullable": true }, "expiry": { "type": "string", "description": "Access expiry, or null for lifetime access.", "nullable": true }, "deviceLimit": { "type": "integer", "description": "Device limit; 0 means unlimited." }, "registeredAt": { "type": "string", "description": "Creation timestamp when available.", "nullable": true }, "lastLogin": { "type": "string", "format": "date-time" }, "systemId": { "type": "string" }, "ipAddress": { "type": "string" }, "country": { "type": "string", "description": "Country code resolved from the connection IP.", "nullable": true }, "features": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] } } }, "required": [] }, "SessionAccess": { "type": "object", "properties": { "token": { "type": "string", "description": "Opaque bearer token. Treat as a credential." }, "sessionId": { "type": "string" }, "application": { "type": "string" }, "identityId": { "type": "string" }, "identity": { "$ref": "#/components/schemas/Identity" }, "expiresAt": { "type": "string", "format": "date-time" }, "accessDeadline": { "type": "string", "format": "date-time" }, "serverTime": { "type": "string", "format": "date-time" }, "heartbeatSeconds": { "type": "integer", "minimum": 30, "maximum": 3600 }, "jitterSeconds": { "type": "integer" }, "leaseSeconds": { "type": "integer" }, "currentVersion": { "type": "string" }, "update": { "$ref": "#/components/schemas/ReleaseUpdate" }, "updateAvailable": { "type": "boolean" } }, "required": [] }, "SessionCheck": { "type": "object", "properties": { "authenticated": { "type": "boolean" }, "application": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ] } }, "serverTime": { "type": "string", "format": "date-time" }, "accessDeadline": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "heartbeatSeconds": { "type": "integer" }, "jitterSeconds": { "type": "integer" }, "leaseSeconds": { "type": "integer" }, "offlineWindowSeconds": { "type": "integer" }, "currentVersion": { "type": "string" }, "update": { "$ref": "#/components/schemas/ReleaseUpdate" }, "updateAvailable": { "type": "boolean" } }, "required": [] }, "CreatedLog": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "RedeemedLicense": { "type": "object", "properties": { "expiry": { "type": "string", "description": "Resulting access expiry, or null.", "nullable": true }, "plan": { "type": "string" } }, "required": [] }, "ReleaseUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "channel": { "type": "string" }, "channelName": { "type": "string" }, "version": { "type": "string" }, "url": { "type": "string", "nullable": true }, "notes": { "type": "string" }, "mode": { "type": "string", "enum": [ "browser" ] } }, "required": [] } } }, "paths": { "/v3/initialize": { "post": { "operationId": "initialize", "summary": "Initialize", "description": "Checks your AppKey and app version. Sign in to receive the update for your assigned release channel.", "tags": [ "Sign-in" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Initialization" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "APP_INITIALIZED", "message": "Application initialized.", "data": { "initialized": true, "application": "MyApp", "version": "1.0.0", "currentVersion": "1.4.0", "updateAvailable": false, "update": { "enabled": true, "requiresLogin": true, "version": "1.4.0", "url": null, "notes": "", "mode": "browser" } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":true,\"code\":\"APP_INITIALIZED\",\"message\":\"Application initialized.\",\"data\":{\"initialized\":true,\"application\":\"MyApp\",\"version\":\"1.0.0\",\"currentVersion\":\"1.4.0\",\"updateAvailable\":false,\"update\":{\"enabled\":true,\"requiresLogin\":true,\"version\":\"1.4.0\",\"url\":null,\"notes\":\"\",\"mode\":\"browser\"}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "0NESh9Dfh/M9hTWyVReuEmRU9Z4L96TclmRb2ShYaEEYbw1xmmzkKQOWFHhbhyhQMxBYpUsu4bIyxjpc+EDxDg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "xt1vq8STI7FxGXv0hnHB6/3AA6ZyU6vQBY1H834b5sO4w9NtbptjLMjSnlwI2PL8YV9G++l7FCV012MFpL4xDA==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "BAn+HZ6DC5am0K2OEbKOMIrc5kFbTL7XL58qHsF8aKoF88vq2NHOCu17Tk82YJEpDIaULbSLlMW7/s54vw5hDw==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "mFMkgneSgIft80Q3X/6d3OCK2CqSpQVhZaSOUYUhaBiAcBUBC8d58VHvGj/+IEzQkbExhPXTPN5T87aTVrO4DA==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "+gqU0JBfbLy9w99hNM+BcFAspBOnEGIh2axD6XJJsuP3vRTNwB6LvITIlGsus3Ey4pYqEmtoMc6N4HH8enNECg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Zewxn6wfFKpMF1b/tcucn7PN5S5CexG6NZHaSEaUMFVDxri12h3Ny7RKfo3TzLk/NZj4ELh18lkTPrztegIeCg==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "MMnKJ4WbbpSlMmTCzVkDBv0sCLElBFsueR4Cj4NYw7P+uomNKeRNNuVk0olGXJbpxw3UrYBuvq1cIb4K8/cpBQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "DPq7gMU1E6Hk+MmLMz1+l66liOisJ8PmZVpg7tXmDea4+lZWUTxcVWaOBdGznSDDMRdQD2juYFodWJ97SBZpBg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "psNBl29qbiHoFgVQch7ejR76EONRzOjYvWsqzg+KE8VZlKLLRDh7ejgHnx2pM97Pdi2JEF0sy2SCoVzFWxD8Cw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appKey": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,31}_[a-f0-9]{48}$", "description": "Application identifier copied from the dashboard. Not an Elite Key or Bot Key." }, "version": { "type": "string", "description": "Version of the application making this request, for example 1.0.0." } }, "required": [ "appKey", "version" ] }, "example": { "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0" } } } }, "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Random nonce for binding and verifying the signed response.", "example": "a6e4c18b379520dfa6e4c18b379520df" } ], "x-fern-examples": [ { "name": "Successful", "request": { "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df" }, "response": { "body": { "success": true, "code": "APP_INITIALIZED", "message": "Application initialized.", "data": { "initialized": true, "application": "MyApp", "version": "1.0.0", "currentVersion": "1.4.0", "updateAvailable": false, "update": { "enabled": true, "requiresLogin": true, "version": "1.4.0", "url": null, "notes": "", "mode": "browser" } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/initialize\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"21fb09659ee65b079a77bbc4bb067d1c19f24b052c63459fe039b2c11fc66507\"},\"response\":{\"success\":true,\"code\":\"APP_INITIALIZED\",\"message\":\"Application initialized.\",\"data\":{\"initialized\":true,\"application\":\"MyApp\",\"version\":\"1.0.0\",\"currentVersion\":\"1.4.0\",\"updateAvailable\":false,\"update\":{\"enabled\":true,\"requiresLogin\":true,\"version\":\"1.4.0\",\"url\":null,\"notes\":\"\",\"mode\":\"browser\"}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "0NESh9Dfh/M9hTWyVReuEmRU9Z4L96TclmRb2ShYaEEYbw1xmmzkKQOWFHhbhyhQMxBYpUsu4bIyxjpc+EDxDg==" } } } } ] } }, "/v3/challenge": { "post": { "operationId": "prepareSignIn", "summary": "Prepare sign-in", "description": "Creates a single-use login challenge for an Ed25519 installation public key. Challenges expire after two minutes. Sign the exact challenge payload together with the normalized login operation; the SDK handles this.", "tags": [ "Sign-in" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Challenge" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "CHALLENGE_CREATED", "message": "Request completed.", "data": { "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "payload": "{\"id\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"purpose\":\"login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\"}", "expiresAt": "2026-10-24T12:02:00.000Z" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":true,\"code\":\"CHALLENGE_CREATED\",\"message\":\"Request completed.\",\"data\":{\"challengeId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"payload\":\"{\\\"id\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"purpose\\\":\\\"login\\\",\\\"nonce\\\":\\\"a6e4c18b379520dfa6e4c18b379520df\\\"}\",\"expiresAt\":\"2026-10-24T12:02:00.000Z\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "+WALwSetkH00QXd9ISCyBDHeaHxcwftp2hnPerb7FsWhnooaP1Za42tS7h04X1Lbk6Z5oXbHE6t1rRHaNUS6DA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "tgAhRRUwoQyNxrlJoqidqjpF9EU0E7z16nVVWCi+e0yVMivR+96dSOiQGZ7+vDFIX4tJOhwjaPE1SFEO2nsMDg==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "2p9AwHDPtSjoFGRxdl+LrlklPxTUyKmE0Vq+m5lugb2vwuoVxNHojrg7JENB/gTIKDlPGQEL7X0IWg14kwvjCA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "7IFSSlgY1wSGir0hihDzLXWbYWqGS3Ibsn7ERDeD7Y6zaVLY3zljg59EDBqmtfZ1nXSR9Z1UibT3IxZ+Wj6cBw==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "1tkhliqVp/JM/2pQBihu8v1RyobXmMTLJk1cIQ3rUPg+damrkXJkZ2+n5WY9ERZ7mFvj8fwlyz06jjpMOtXPCQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "BIIMKXoUvbuSBkcF83eIwoKQ4Pp1ovPXugwl2ELakTfS1HG8yUsPnuJ+gL74k+S4+R1ebmRtSNMRHWB3aTDxBw==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "ZAGUInWo2t0QFyX4xrsm2df1Y58tEKChh6UBuQrWhZ63BRZhCcbw8AztPz/piB6RDbHxMP/TteUFHjsRRyYQAw==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "1S3LPb0anhxLC0IOUuHyy13l4lusgsgc3baodFNamJ1e5kSqeFZGXXG7OuRK15q0oQ64itu6kAfdFtmqAwzdDg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "rjNeHVkmZbq5cK4c3k/bGY6+jvrHUF/H6BSknGeP62ETmDArHMzHAT9z0Zqi/G6qj+CadYFZAJqTjAMmc40fAQ==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appKey": { "type": "string", "description": "Application identifier copied from the dashboard. Not an Elite Key or Bot Key." }, "installationPublicKey": { "type": "string", "description": "PEM-encoded Ed25519 public key for this installation. Never send its private key." } }, "required": [ "appKey", "installationPublicKey" ] }, "example": { "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "installationPublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n" } } } }, "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Random nonce for binding and verifying the signed response.", "example": "a6e4c18b379520dfa6e4c18b379520df" } ], "x-fern-examples": [ { "name": "Successful", "request": { "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "installationPublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df" }, "response": { "body": { "success": true, "code": "CHALLENGE_CREATED", "message": "Request completed.", "data": { "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "payload": "{\"id\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"purpose\":\"login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\"}", "expiresAt": "2026-10-24T12:02:00.000Z" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"12612ce36146ab8e43cff80aa705a016da8a08fd9a8147b09d1135d3f79e1db3\"},\"response\":{\"success\":true,\"code\":\"CHALLENGE_CREATED\",\"message\":\"Request completed.\",\"data\":{\"challengeId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"payload\":\"{\\\"id\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"purpose\\\":\\\"login\\\",\\\"nonce\\\":\\\"a6e4c18b379520dfa6e4c18b379520df\\\"}\",\"expiresAt\":\"2026-10-24T12:02:00.000Z\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "+WALwSetkH00QXd9ISCyBDHeaHxcwftp2hnPerb7FsWhnooaP1Za42tS7h04X1Lbk6Z5oXbHE6t1rRHaNUS6DA==" } } } } ] } }, "/v3/login": { "post": { "operationId": "login", "summary": "Login", "description": "Sign in with a license key, username and password, or an approved device. AuthlyX checks access and returns a session. Prepare sign-in first to get the required challenge proof.", "tags": [ "Sign-in" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SessionAccess" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "LOGIN_SUCCESS", "message": "Request completed.", "data": { "token": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "sessionId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "application": "MyApp", "identityId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "identity": { "type": "license", "name": "4J8N-7P2C-9K6R-3W5M", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "email": "alex@example.com", "plan": "Premium", "expiry": "2026-11-24T12:00:00.000Z", "deviceLimit": 2, "registeredAt": "2026-10-01T09:15:00.000Z", "lastLogin": "2026-10-24T12:00:00.000Z", "systemId": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ipAddress": "197.210.54.18", "country": "NG", "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "updateAvailable": true, "currentVersion": "1.4.0", "update": { "enabled": true, "channel": "stable", "channelName": "Stable", "version": "1.4.0", "url": "https://example.com/ger-1.4.0.zip", "notes": "Improves sign-in after waking from sleep.", "mode": "browser" }, "serverTime": "2026-10-24T12:00:00.000Z", "accessDeadline": "2026-10-24T12:15:00.000Z", "expiresAt": "2026-10-25T12:00:00.000Z", "heartbeatSeconds": 600, "jitterSeconds": 15, "leaseSeconds": 900 }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":true,\"code\":\"LOGIN_SUCCESS\",\"message\":\"Request completed.\",\"data\":{\"token\":\"c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140\",\"sessionId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"application\":\"MyApp\",\"identityId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"identity\":{\"type\":\"license\",\"name\":\"4J8N-7P2C-9K6R-3W5M\",\"licenseKey\":\"4J8N-7P2C-9K6R-3W5M\",\"email\":\"alex@example.com\",\"plan\":\"Premium\",\"expiry\":\"2026-11-24T12:00:00.000Z\",\"deviceLimit\":2,\"registeredAt\":\"2026-10-01T09:15:00.000Z\",\"lastLogin\":\"2026-10-24T12:00:00.000Z\",\"systemId\":\"S-1-5-21-3349523261-4242746980-1390621393-1001\",\"ipAddress\":\"197.210.54.18\",\"country\":\"NG\",\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"updateAvailable\":true,\"currentVersion\":\"1.4.0\",\"update\":{\"enabled\":true,\"channel\":\"stable\",\"channelName\":\"Stable\",\"version\":\"1.4.0\",\"url\":\"https://example.com/ger-1.4.0.zip\",\"notes\":\"Improves sign-in after waking from sleep.\",\"mode\":\"browser\"},\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"accessDeadline\":\"2026-10-24T12:15:00.000Z\",\"expiresAt\":\"2026-10-25T12:00:00.000Z\",\"heartbeatSeconds\":600,\"jitterSeconds\":15,\"leaseSeconds\":900},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Fn0TREHxtLweyXtMHpC/dA5YAvmced7hwgPK0TKfms5utHEDSP7v8A/5PYbtCvBdkARQhaogsdxYI7JndtiDDw==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "mrcpMYm8pGCVf+Qow5LhpfiRfZBEWv/zuX29ZXAw505fGhF8Woz4K2CzoWsNpQATSxv49vzHIuL1DxunbM8xBA==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "DS03hSTYuo7oB/a0fxlvc6pT8NC0eP12pTOamA4RIwD4HFVGeprdnjRn/AAeo+XQIRm/9t1u47KgItVZeuprCA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "n4Rab5hNcjP8gBrfU1zFvvxLCrcjas4RHxVfWTmyCP3/MqP79SLNpuBRjbawlT3yUocX/XvoJ6n4EHhtMYh6AQ==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "paqi/NT3rOdZntsLHIVso5DJmTi4n0MDAMxYpLMAsdGyTi8gP9kjOacGNiVV7X76G5Xg4meqICv/8tZxi4S9Bg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "sXWixmJGKs95tg3qe2Kkx+nb0puAxQNQWaBNpZd70ddQjaMX67vju9/EKqiXHrqsLi8uBe4rLIoJoKWU5F7CBQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "w01OW1Byf91VyhpglqEtK2cEM2WtarfauWS7L8mGKv/M5xAF/S96ZgFJWDP9rLiVMjtOtNosNXTQ4qtWwbW1CQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "iRsfgNTKOnDt1hFiKMjYujqZsbx3Q5Nk1CZTgC0wjwkGc8piqSS9XxFt8CvQUiZ0o5GrFVhs6lJeRgZcZf8jDg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "AZqm65VX2hAGph38s0sb7ffbVBTRA8OjNQMayPkD6cvJAis+GT/B23EIc+CgpN8ZDjAMWH0tiwdvkjNpPZ0OBA==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appKey": { "type": "string", "description": "Application identifier copied from the dashboard. Not an Elite Key or Bot Key." }, "version": { "type": "string", "description": "Version of the application making this request, for example 1.0.0." }, "sid": { "type": "string", "description": "Stable platform system identifier. Windows SDK defaults use the Windows user SID." }, "hash": { "type": "string", "description": "SHA-256 build hash. Required by policy when hash checking is enabled." }, "username": { "type": "string", "description": "App username, required for user and register sign-in. Between 1 and 200 characters." }, "password": { "type": "string", "description": "App password, required for user and register sign-in. Between 1 and 256 characters." }, "licenseKey": { "type": "string", "description": "License key belonging to this app. Required for license sign-in and registration." }, "installationPublicKey": { "type": "string", "description": "PEM-encoded Ed25519 public key for this installation. Never send its private key." }, "challengeId": { "type": "string", "description": "ID from an unexpired single-use challenge for this operation." }, "signature": { "type": "string", "description": "Base64 Ed25519 signature over the challenge proof payload." }, "type": { "type": "string", "enum": [ "license", "user", "device" ], "description": "Sign-in method: user, license, device or register." }, "email": { "type": "string", "format": "email", "description": "Optional app-user email for registration." } }, "required": [ "type", "appKey", "version", "sid", "challengeId", "signature" ] }, "example": { "type": "license", "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } } } }, "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Random nonce for binding and verifying the signed response.", "example": "a6e4c18b379520dfa6e4c18b379520df" } ], "x-fern-examples": [ { "name": "Successful", "request": { "type": "license", "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df" }, "response": { "body": { "success": true, "code": "LOGIN_SUCCESS", "message": "Request completed.", "data": { "token": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "sessionId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "application": "MyApp", "identityId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "identity": { "type": "license", "name": "4J8N-7P2C-9K6R-3W5M", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "email": "alex@example.com", "plan": "Premium", "expiry": "2026-11-24T12:00:00.000Z", "deviceLimit": 2, "registeredAt": "2026-10-01T09:15:00.000Z", "lastLogin": "2026-10-24T12:00:00.000Z", "systemId": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ipAddress": "197.210.54.18", "country": "NG", "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "updateAvailable": true, "currentVersion": "1.4.0", "update": { "enabled": true, "channel": "stable", "channelName": "Stable", "version": "1.4.0", "url": "https://example.com/ger-1.4.0.zip", "notes": "Improves sign-in after waking from sleep.", "mode": "browser" }, "serverTime": "2026-10-24T12:00:00.000Z", "accessDeadline": "2026-10-24T12:15:00.000Z", "expiresAt": "2026-10-25T12:00:00.000Z", "heartbeatSeconds": 600, "jitterSeconds": 15, "leaseSeconds": 900 }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/login\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"f0129ca7ee5f9e7f7b5ff90b613360e1bbc30be61b56fe20f14235c545a63ae2\"},\"response\":{\"success\":true,\"code\":\"LOGIN_SUCCESS\",\"message\":\"Request completed.\",\"data\":{\"token\":\"c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140\",\"sessionId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"application\":\"MyApp\",\"identityId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"identity\":{\"type\":\"license\",\"name\":\"4J8N-7P2C-9K6R-3W5M\",\"licenseKey\":\"4J8N-7P2C-9K6R-3W5M\",\"email\":\"alex@example.com\",\"plan\":\"Premium\",\"expiry\":\"2026-11-24T12:00:00.000Z\",\"deviceLimit\":2,\"registeredAt\":\"2026-10-01T09:15:00.000Z\",\"lastLogin\":\"2026-10-24T12:00:00.000Z\",\"systemId\":\"S-1-5-21-3349523261-4242746980-1390621393-1001\",\"ipAddress\":\"197.210.54.18\",\"country\":\"NG\",\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"updateAvailable\":true,\"currentVersion\":\"1.4.0\",\"update\":{\"enabled\":true,\"channel\":\"stable\",\"channelName\":\"Stable\",\"version\":\"1.4.0\",\"url\":\"https://example.com/ger-1.4.0.zip\",\"notes\":\"Improves sign-in after waking from sleep.\",\"mode\":\"browser\"},\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"accessDeadline\":\"2026-10-24T12:15:00.000Z\",\"expiresAt\":\"2026-10-25T12:00:00.000Z\",\"heartbeatSeconds\":600,\"jitterSeconds\":15,\"leaseSeconds\":900},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Fn0TREHxtLweyXtMHpC/dA5YAvmced7hwgPK0TKfms5utHEDSP7v8A/5PYbtCvBdkARQhaogsdxYI7JndtiDDw==" } } } } ] } }, "/v3/register": { "post": { "operationId": "register", "summary": "Register", "description": "Creates an app user with a username, password and unused license. Prepare sign-in first and sign the register operation. This is not AuthlyX dashboard registration.", "tags": [ "Sign-in" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SessionAccess" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "LOGIN_SUCCESS", "message": "Request completed.", "data": { "token": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "sessionId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "application": "MyApp", "identityId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "identity": { "type": "user", "name": "4J8N-7P2C-9K6R-3W5M", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "email": "alex@example.com", "plan": "Premium", "expiry": "2026-11-24T12:00:00.000Z", "deviceLimit": 2, "registeredAt": "2026-10-01T09:15:00.000Z", "lastLogin": "2026-10-24T12:00:00.000Z", "systemId": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ipAddress": "197.210.54.18", "country": "NG", "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "updateAvailable": true, "currentVersion": "1.4.0", "update": { "enabled": true, "channel": "stable", "channelName": "Stable", "version": "1.4.0", "url": "https://example.com/ger-1.4.0.zip", "notes": "Improves sign-in after waking from sleep.", "mode": "browser" }, "serverTime": "2026-10-24T12:00:00.000Z", "accessDeadline": "2026-10-24T12:15:00.000Z", "expiresAt": "2026-10-25T12:00:00.000Z", "heartbeatSeconds": 600, "jitterSeconds": 15, "leaseSeconds": 900 }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":true,\"code\":\"LOGIN_SUCCESS\",\"message\":\"Request completed.\",\"data\":{\"token\":\"c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140\",\"sessionId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"application\":\"MyApp\",\"identityId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"identity\":{\"type\":\"user\",\"name\":\"4J8N-7P2C-9K6R-3W5M\",\"licenseKey\":\"4J8N-7P2C-9K6R-3W5M\",\"email\":\"alex@example.com\",\"plan\":\"Premium\",\"expiry\":\"2026-11-24T12:00:00.000Z\",\"deviceLimit\":2,\"registeredAt\":\"2026-10-01T09:15:00.000Z\",\"lastLogin\":\"2026-10-24T12:00:00.000Z\",\"systemId\":\"S-1-5-21-3349523261-4242746980-1390621393-1001\",\"ipAddress\":\"197.210.54.18\",\"country\":\"NG\",\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"updateAvailable\":true,\"currentVersion\":\"1.4.0\",\"update\":{\"enabled\":true,\"channel\":\"stable\",\"channelName\":\"Stable\",\"version\":\"1.4.0\",\"url\":\"https://example.com/ger-1.4.0.zip\",\"notes\":\"Improves sign-in after waking from sleep.\",\"mode\":\"browser\"},\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"accessDeadline\":\"2026-10-24T12:15:00.000Z\",\"expiresAt\":\"2026-10-25T12:00:00.000Z\",\"heartbeatSeconds\":600,\"jitterSeconds\":15,\"leaseSeconds\":900},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "pDMwdLX2XWarhAuWEuIyEUeyfJPiM51qCg0pJf4EUpJ2ZTzhwjDkJoepUewNb7XpDfPg6siTexHXv2iE5pFOCg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "iknFRiKVHEDoFLhg9lrP/8AchNiIGPUM4sWK0kPGz5LpdObq9a50xIkKgQUR5a73QELcDHXMbAFwmVaeqoieCA==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "yB/aT/ZCi5BoT2j0ffYCh7JmmZBjjtnPUEh1OQMi3J1+mnRgEBqIngHBUGgVwcjoyqHkpnvpcXbxu7OgfX+pDA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "GrMzvleJs3VwBaA9FabnmtbggyZkMJN9q3ilwp0g2zI+P6SyYbProlAObimitswasZlNfD8GCnK4766ldWArBw==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "z1ChuuU3vkJZFWCk/8yV0Ei4L9s24qqV+hC8z7jtzvFdfwv8lxgE2ffK8V2LbUmrC31Vg08QsHXZ2i6k+M2/BQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "mz9DR5n/Ea8RCf6OF7vRM8vdQGTH02J4Awv2oEmgJLMl9SdAATPnD9v6vwIQgEoEOoLX+S4QR0TMosFYhb63Ag==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "XJiqb9K2oj5rC3SboouniRanlxD1HMG5w3HZJTEZ/RluiYhm+ANBAf1eTSpFDhGsQoSxJpz1x6R/OVK6wHFUDQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "ElMjh0yArhrQDGhbiov6dzU2vXUMIqSee8BOzDBQ8PaeEJ/taAfvuYV0+5/xhgp3cNX7ZQKmWXGddmHCiHsGAg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "3goXYvs3VycWVy+3VveisK+eq6Wt7iGdorTLhvmk4nNEnnNYgKs62Me/NfWdz919UcW7T13JelywL5kWXmFlBQ==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appKey": { "type": "string", "description": "Application identifier copied from the dashboard. Not an Elite Key or Bot Key." }, "version": { "type": "string", "description": "Version of the application making this request, for example 1.0.0." }, "sid": { "type": "string", "description": "Stable platform system identifier. Windows SDK defaults use the Windows user SID." }, "hash": { "type": "string", "description": "SHA-256 build hash. Required by policy when hash checking is enabled." }, "username": { "type": "string", "description": "App username, required for user and register sign-in. Between 1 and 200 characters." }, "password": { "type": "string", "description": "App password, required for user and register sign-in. Between 1 and 256 characters." }, "licenseKey": { "type": "string", "description": "License key belonging to this app. Required for license sign-in and registration." }, "installationPublicKey": { "type": "string", "description": "PEM-encoded Ed25519 public key for this installation. Never send its private key." }, "challengeId": { "type": "string", "description": "ID from an unexpired single-use challenge for this operation." }, "signature": { "type": "string", "description": "Base64 Ed25519 signature over the challenge proof payload." }, "type": { "type": "string", "enum": [ "register" ], "default": "register" }, "email": { "type": "string", "format": "email", "description": "Optional app-user email for registration." } }, "required": [ "type", "appKey", "version", "sid", "challengeId", "signature" ] }, "example": { "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hash": "a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f", "username": "alex", "password": "River-Glass-29", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "installationPublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n", "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==", "type": "register", "email": "alex@example.com" } } } }, "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Random nonce for binding and verifying the signed response.", "example": "a6e4c18b379520dfa6e4c18b379520df" } ], "x-fern-examples": [ { "name": "Successful", "request": { "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hash": "a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f", "username": "alex", "password": "River-Glass-29", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "installationPublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n", "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==", "type": "register", "email": "alex@example.com" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df" }, "response": { "body": { "success": true, "code": "LOGIN_SUCCESS", "message": "Request completed.", "data": { "token": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "sessionId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "application": "MyApp", "identityId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "identity": { "type": "user", "name": "4J8N-7P2C-9K6R-3W5M", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "email": "alex@example.com", "plan": "Premium", "expiry": "2026-11-24T12:00:00.000Z", "deviceLimit": 2, "registeredAt": "2026-10-01T09:15:00.000Z", "lastLogin": "2026-10-24T12:00:00.000Z", "systemId": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ipAddress": "197.210.54.18", "country": "NG", "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "updateAvailable": true, "currentVersion": "1.4.0", "update": { "enabled": true, "channel": "stable", "channelName": "Stable", "version": "1.4.0", "url": "https://example.com/ger-1.4.0.zip", "notes": "Improves sign-in after waking from sleep.", "mode": "browser" }, "serverTime": "2026-10-24T12:00:00.000Z", "accessDeadline": "2026-10-24T12:15:00.000Z", "expiresAt": "2026-10-25T12:00:00.000Z", "heartbeatSeconds": 600, "jitterSeconds": 15, "leaseSeconds": 900 }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/register\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"325d5c115f5b186a029eaa9268e4c86153a561df9dfb7da7a04b889d323edc18\"},\"response\":{\"success\":true,\"code\":\"LOGIN_SUCCESS\",\"message\":\"Request completed.\",\"data\":{\"token\":\"c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140\",\"sessionId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"application\":\"MyApp\",\"identityId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"identity\":{\"type\":\"user\",\"name\":\"4J8N-7P2C-9K6R-3W5M\",\"licenseKey\":\"4J8N-7P2C-9K6R-3W5M\",\"email\":\"alex@example.com\",\"plan\":\"Premium\",\"expiry\":\"2026-11-24T12:00:00.000Z\",\"deviceLimit\":2,\"registeredAt\":\"2026-10-01T09:15:00.000Z\",\"lastLogin\":\"2026-10-24T12:00:00.000Z\",\"systemId\":\"S-1-5-21-3349523261-4242746980-1390621393-1001\",\"ipAddress\":\"197.210.54.18\",\"country\":\"NG\",\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"updateAvailable\":true,\"currentVersion\":\"1.4.0\",\"update\":{\"enabled\":true,\"channel\":\"stable\",\"channelName\":\"Stable\",\"version\":\"1.4.0\",\"url\":\"https://example.com/ger-1.4.0.zip\",\"notes\":\"Improves sign-in after waking from sleep.\",\"mode\":\"browser\"},\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"accessDeadline\":\"2026-10-24T12:15:00.000Z\",\"expiresAt\":\"2026-10-25T12:00:00.000Z\",\"heartbeatSeconds\":600,\"jitterSeconds\":15,\"leaseSeconds\":900},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "pDMwdLX2XWarhAuWEuIyEUeyfJPiM51qCg0pJf4EUpJ2ZTzhwjDkJoepUewNb7XpDfPg6siTexHXv2iE5pFOCg==" } } } } ] } }, "/v3/session/check": { "post": { "operationId": "checkSession", "summary": "Check session", "description": "Checks the signed-in identity and its current access policies, then renews the server-issued access deadline. The session stays bound to its original identity, app, system ID and installation key.", "tags": [ "Sessions" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SessionCheck" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "SESSION_VALID", "message": "Your session is active.", "data": { "authenticated": true, "application": "MyApp", "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" }, "updateAvailable": true, "currentVersion": "1.4.0", "update": { "enabled": true, "channel": "stable", "channelName": "Stable", "version": "1.4.0", "url": "https://example.com/ger-1.4.0.zip", "notes": "Improves sign-in after waking from sleep.", "mode": "browser" }, "serverTime": "2026-10-24T12:00:00.000Z", "accessDeadline": "2026-10-24T12:15:00.000Z", "expiresAt": "2026-10-25T12:00:00.000Z", "heartbeatSeconds": 600, "jitterSeconds": 15, "leaseSeconds": 900, "offlineWindowSeconds": 86400 }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"SESSION_VALID\",\"message\":\"Your session is active.\",\"data\":{\"authenticated\":true,\"application\":\"MyApp\",\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"},\"updateAvailable\":true,\"currentVersion\":\"1.4.0\",\"update\":{\"enabled\":true,\"channel\":\"stable\",\"channelName\":\"Stable\",\"version\":\"1.4.0\",\"url\":\"https://example.com/ger-1.4.0.zip\",\"notes\":\"Improves sign-in after waking from sleep.\",\"mode\":\"browser\"},\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"accessDeadline\":\"2026-10-24T12:15:00.000Z\",\"expiresAt\":\"2026-10-25T12:00:00.000Z\",\"heartbeatSeconds\":600,\"jitterSeconds\":15,\"leaseSeconds\":900,\"offlineWindowSeconds\":86400},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "n37HxwsTeSEBiamuRJ98w3EqU9NP6UjcDmr2MBVQhfvQJsgCvHPt1k/SUevLXNcRBYoycYA/FdAwuMPKdvcDAg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "iTw81bNQN/k7YxCPcJ18bklDfZp527dZ58KmLVP0TbSUZUXnAtom1SAJEP45ek88535tne/PsQKP9yhT4gH2DQ==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "YUfwdjyjdquoRoI59bBBa9Zo0l5YcndhfiHQ51uloK9dDmRLU0T5/J+6OniqKGfxVTYF6+Be2jcDr0D/esouDg==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "KVyIyG1d2nQkJAfog1L+gPTUSkVYBt83KNP+6bf3D5AMI6wwsRdADJGP9URdUv2MCpsXjfVidZ9rH+ktoAOTDg==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "jJR52JZfcrrRWDrwskWmxFnYo6FsA/CJyA6y2qJX76UM7TCCUDrjcjdCWYGsdJ37LPNA/XubFefoVdlGS3ldDg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "krj/lZALxvQFP+AvZJavqVFtDRPcTxfYEVzKBGur8EMJIhqXx4KCar96PbFCPgbWe2RkRgUH0boGar//XpNiBQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "OsWA/l5Ww5Z8GxrnsBqkugnRoRKJTNdVNEO6uhZRzsH5BWJtnKvAizUH414FE+yI8z5bdJ8M7mtgr+7363rrBQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "HD0/gECGkwDg3+pwyDH5snlIuy3wN3y0h8fLqOR9Uu5sPrmPFnJH9gl/Di00Gyi6piv/izUGRyxA1UjILg4/CQ==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "VDkQYzOMQS288PP8YPzvAgu+HgVenr2ArMta+LPXcMvqCju8Nfe2W9WzjkTuPrKTjEj41MQcKMAMYpu83mn4Cg==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": {}, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "SESSION_VALID", "message": "Your session is active.", "data": { "authenticated": true, "application": "MyApp", "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" }, "updateAvailable": true, "currentVersion": "1.4.0", "update": { "enabled": true, "channel": "stable", "channelName": "Stable", "version": "1.4.0", "url": "https://example.com/ger-1.4.0.zip", "notes": "Improves sign-in after waking from sleep.", "mode": "browser" }, "serverTime": "2026-10-24T12:00:00.000Z", "accessDeadline": "2026-10-24T12:15:00.000Z", "expiresAt": "2026-10-25T12:00:00.000Z", "heartbeatSeconds": 600, "jitterSeconds": 15, "leaseSeconds": 900, "offlineWindowSeconds": 86400 }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"SESSION_VALID\",\"message\":\"Your session is active.\",\"data\":{\"authenticated\":true,\"application\":\"MyApp\",\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"},\"updateAvailable\":true,\"currentVersion\":\"1.4.0\",\"update\":{\"enabled\":true,\"channel\":\"stable\",\"channelName\":\"Stable\",\"version\":\"1.4.0\",\"url\":\"https://example.com/ger-1.4.0.zip\",\"notes\":\"Improves sign-in after waking from sleep.\",\"mode\":\"browser\"},\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"accessDeadline\":\"2026-10-24T12:15:00.000Z\",\"expiresAt\":\"2026-10-25T12:00:00.000Z\",\"heartbeatSeconds\":600,\"jitterSeconds\":15,\"leaseSeconds\":900,\"offlineWindowSeconds\":86400},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "n37HxwsTeSEBiamuRJ98w3EqU9NP6UjcDmr2MBVQhfvQJsgCvHPt1k/SUevLXNcRBYoycYA/FdAwuMPKdvcDAg==" } } } } ] } }, "/v3/session/logout": { "post": { "operationId": "signOut", "summary": "Sign out", "description": "Revokes the current server session. Clear local authorization and stop heartbeat work. This endpoint does not terminate the developer application.", "tags": [ "Sessions" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "SESSION_ENDED", "message": "You have signed out.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"SESSION_ENDED\",\"message\":\"You have signed out.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "MoZTPY2/82qbjR239n1LIdY7ax+XEsFqPyq1KbTcQEKm7lsvbrGQrC01PgfWfi7PCLsRlaqnxzkEQXvE52kSDA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "o/AbvnzZNqyEHBhll3Rh0uKWrO2T6g29JA2to9dxrEXCoOqoPxOAOfn7Qn6A7olcB3b6GIF4sE3DZ5XPUhUdBg==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "hQO178NgzpviiKbVgHqnp3GRQz8BAQwps7PaTvZbhwugQGmXLlUKAAqvY2biIj84UM7peoOgfWkT1K04SrrCCg==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "m/ViVbcbEt4UIbaVHGI9dkil3gQiQtdUmVVyg7vLfi13UO8cFSvJ9jlqgfKzE3FtaiYoysecSwpsU/FHBahEBw==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "ZD5y2PGCvcDFOuiwKSJaKDyBjAgKLw6Wsabaa6g0RMCB56FZwLlUiK/1pUeOPwgrXe9bueYrwalgAnlSDSRSDg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "F8cw72YUah5qqFUOPLE25/2eU5FttINAfTMxEn3JOYVct4GZmeSaw+ncPyjFrWA8Dq2gsx78X7b7W0K67VlBAA==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "rKZmEAKveF/I37fS7boPWyfSo5rY5qCzKVSZr54ojgKCLg5hpqhsdrHw/RJ3z4V0lP1KNc1Ukvuj3rU89GphDQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "K6Nqf2NwfisHsUUUs/d5ZIRuIaJgWzesPxNqkCCWVp1powIsZ7h3Qs/5Pilg2Jvic2tSSvTVn9Wom5+woG5BAw==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "oKvJH5e/HySTHdRAZYirbzM6a8CdoLeHr45GsJXUGa2AQyauyA8RRH2R69UumVCS/MzpdtmBGfiq6gH8ahd2Cw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": {}, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "SESSION_ENDED", "message": "You have signed out.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/session/logout\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"SESSION_ENDED\",\"message\":\"You have signed out.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "MoZTPY2/82qbjR239n1LIdY7ax+XEsFqPyq1KbTcQEKm7lsvbrGQrC01PgfWfi7PCLsRlaqnxzkEQXvE52kSDA==" } } } } ] } }, "/v3/offline/challenge": { "post": { "operationId": "prepareOfflineAccess", "summary": "Prepare offline access", "description": "Requires a valid V3 session and an enabled app offline window. Creates a challenge tied to that session and installation. It does not grant an offline permit by itself.", "tags": [ "Offline access" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Challenge" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "CHALLENGE_CREATED", "message": "Request completed.", "data": { "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "payload": "{\"id\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"purpose\":\"offline\",\"sessionId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}", "expiresAt": "2026-10-24T12:02:00.000Z" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"CHALLENGE_CREATED\",\"message\":\"Request completed.\",\"data\":{\"challengeId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"payload\":\"{\\\"id\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"purpose\\\":\\\"offline\\\",\\\"sessionId\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\"}\",\"expiresAt\":\"2026-10-24T12:02:00.000Z\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "vaMMZlSA38Csmd9XY3N4y2E8AoY+nK663QfZD8lvVSAkgxUD0wp+JYaD2uA/NmORGKVj/XERrLV+Z52fvmtPBg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "/1Iy0wQmefq7PXH2xBW8pkERCma/UQSrcQKgvZBzKnNJSrWqMtRPdrJmkc9zqaZeiZ9fZyRAn89eIhdo5p5VCw==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "2uUEMxKZwUfqgD+HdfgWJoU+fbI2cv+mhrqDFDn/TNl954/376lF82URsDkWM/oTF77LDG6uafgGVa/0f/yeCA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Oqaq6fXlLPSgj1mGJwewUJYctxBDbTJQPaWpZpl6Uxz5zBCG1rDxktH+jqjkAysQMxgp4Wubi2M7PMiei1fvBA==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Rjv78RAB/te1t4f1RmknAHGAnmmMcqaVURe0z28BlSD5RdvLVpXoUNKWabkTgsqbTcn0PIMvEDq2TlCpPUccCg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "lEmRIsQFtYQv5eGnIMDe4uZDj67C3UGux6Qjr+I7XgZdf8n1vPg4xbs450xaueDjAEq/14XfwNDWPRPIbNCLBQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "FAuAwz6jrD1ALJaX8BLmRBHhZww4cBloyJ5efJlbPgXY7PEJd/m7KEUsx2d7Myk7XC3DdEnR4kzDGGlkucVUCA==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "HSdmdQIAGJp0acE6N394Ete5pJGvuD6ppaj5J/SUv+JtQpf7e6YM3+W7KSHgEhym/LaGEDirvxkfulsMzdZdDA==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "oOOD1Bn64oFvihGzW6it3KPl+J4MoEcovrGqQnTG0FfJYoj4o6Myrd0GLbU6GMWNS3HWOHTbW871QAOuPcL9Cg==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": {}, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "CHALLENGE_CREATED", "message": "Request completed.", "data": { "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "payload": "{\"id\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"purpose\":\"offline\",\"sessionId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}", "expiresAt": "2026-10-24T12:02:00.000Z" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/challenge\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"CHALLENGE_CREATED\",\"message\":\"Request completed.\",\"data\":{\"challengeId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"payload\":\"{\\\"id\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"purpose\\\":\\\"offline\\\",\\\"sessionId\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\"}\",\"expiresAt\":\"2026-10-24T12:02:00.000Z\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "vaMMZlSA38Csmd9XY3N4y2E8AoY+nK663QfZD8lvVSAkgxUD0wp+JYaD2uA/NmORGKVj/XERrLV+Z52fvmtPBg==" } } } } ] } }, "/v3/offline/permit": { "post": { "operationId": "getOfflinePermit", "summary": "Get offline permit", "description": "Exchanges the offline challenge proof for a signed, installation-bound permit. Its deadline cannot exceed the app window or identity entitlement. Offline access cannot immediately learn about later bans.", "tags": [ "Offline access" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignedArtifact" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "OFFLINE_PERMIT_ISSUED", "message": "Request completed.", "data": { "keyId": "offline-2026-01", "signedPayload": "{\"appId\":\"d52d697c-490e-4d0e-bbea-0884f2db409c\",\"subjectId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"installationKeyHash\":\"a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f\",\"issuedAt\":1792843200000,\"expiresAt\":1792929600000}", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":true,\"code\":\"OFFLINE_PERMIT_ISSUED\",\"message\":\"Request completed.\",\"data\":{\"keyId\":\"offline-2026-01\",\"signedPayload\":\"{\\\"appId\\\":\\\"d52d697c-490e-4d0e-bbea-0884f2db409c\\\",\\\"subjectId\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"installationKeyHash\\\":\\\"a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f\\\",\\\"issuedAt\\\":1792843200000,\\\"expiresAt\\\":1792929600000}\",\"signature\":\"DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "4H5SG5Dm+6NoW8tgO9RdukGkFVSGaM5k5Bk8klRwQfxV4Afm3DU329US67O9hJ6lbEkLMY8pMXef2aAASXsyCA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "bZzhLjoFltqv1y5xKPD85VBrYz2+5HbUgLgkceLYa74piDSTV/CXBiOsHr7TRh7vJ9zGEtkvF/ILDch9S6KWCA==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "QA5RVoOTX0PnucAcATAoHTN1A3TavYSCzPtfSeONcDHoha/PYZTK7uoGO+vMP021Q4tRnIP3euzSoILrwQX9Bw==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "lX16+8RWT0yBT7xiWh1yeCdEMMTSWTWAMidJHV2RhZPaMcxtW7ML5wsU778fhlLrzvBtzQtfTqsskb7FWwpaCg==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "oiPPqpXsZhNQHGPxRYvKuwylve1OjzIpZfgfzEzxMi9VaGF5Mg7970jKRKQ+1/qtih+cHc0M5CyQAGztVjdHBQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "XgI6Qm4Cn/AbfMyh6zb3EqzpDx86DrAoAAb1S4vgoWUV9UJMY7UnDNNouAskTcYNPfNFy++jsRpHFZxJLslWBw==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "WzmW9cl8OvwKD44XZ8H1g/wAmX85Z3RZe+wIFj+6mEtUdeJH4zXFhpFiQL1+FmALsbaUgFGzN5ezTKfk85VHDw==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "e9V1sbWCTKD4+siRZXlMINDJI0z5nsEqR531lvJRUnm3k+GPbO0XJYz5/oLskdZL+AJu5PW6tyyqmUsovWVTBA==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "hk+yC8EdNBh9lKczrmkrYNOrKqmAm6lUvg3zVKVrgnsGxuOccetvpgrwJ3XnIMvbNZSU/17sqCGSRO3dlijBDw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "description": "ID from an unexpired single-use challenge for this operation." }, "signature": { "type": "string", "description": "Base64 Ed25519 signature over the challenge proof payload." } }, "required": [ "challengeId", "signature" ] }, "example": { "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "OFFLINE_PERMIT_ISSUED", "message": "Request completed.", "data": { "keyId": "offline-2026-01", "signedPayload": "{\"appId\":\"d52d697c-490e-4d0e-bbea-0884f2db409c\",\"subjectId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"installationKeyHash\":\"a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f\",\"issuedAt\":1792843200000,\"expiresAt\":1792929600000}", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/offline/permit\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fa5700397a2839bdcabf577523e270b49e3c3b7b6ba22b76e69f40ec85fddd4e\"},\"response\":{\"success\":true,\"code\":\"OFFLINE_PERMIT_ISSUED\",\"message\":\"Request completed.\",\"data\":{\"keyId\":\"offline-2026-01\",\"signedPayload\":\"{\\\"appId\\\":\\\"d52d697c-490e-4d0e-bbea-0884f2db409c\\\",\\\"subjectId\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"installationKeyHash\\\":\\\"a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f\\\",\\\"issuedAt\\\":1792843200000,\\\"expiresAt\\\":1792929600000}\",\"signature\":\"DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "4H5SG5Dm+6NoW8tgO9RdukGkFVSGaM5k5Bk8klRwQfxV4Afm3DU329US67O9hJ6lbEkLMY8pMXef2aAASXsyCA==" } } } } ] } }, "/v3/data/get": { "post": { "operationId": "readAVariable", "summary": "Read a variable", "description": "Reads an active cloud variable by name from the signed-in application. A paused or missing variable is rejected. Values become current when the app next fetches them; there is no unsolicited push.", "tags": [ "Cloud Variables" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CloudVariable" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "APP_VALUE_FOUND", "message": "Request completed.", "data": { "name": "download_url", "value": "https://downloads.example.com/ger/1.4.1.zip" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":true,\"code\":\"APP_VALUE_FOUND\",\"message\":\"Request completed.\",\"data\":{\"name\":\"download_url\",\"value\":\"https://downloads.example.com/ger/1.4.1.zip\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Q1pGBWh0Bkm/eq/OBXb8K7Wqdc+OvftAD57oJHVkFLPagvUveFyr/WHND4l+8AaagTTPzODW4T8H5GW3fq58CA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "gImiNjSRnb87uaXqW24I54fRpB1HTot+vIOT9X8skYDTZkvgHvidBh5EzA1KpYw6ZYexZsZaB4NCM9cxROlxCg==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "qxZYttTIbDNuwle15E8UBFf1h+jch/MFXG8uLUutsC6CHvXFgqmI1i5jGWSQCXjcCfK2pGbJuccWnoQUroJVCA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "X2yHdRo5iDb6gOp5WsLc4eqcHu8sf52TxL+bCgLJEGpdVyA/roR6fLuZz/6V/ITaWXXWN2mOSNxliL+/4QmsAA==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "iiEc0VRm3CNDJAtsmFZgEBXYLKdjg4XAczZHpTrq7bwkBha5oklbtrkFejQlQlpHEJiOwvGVmv/edEL6v8CBBg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "FblPDJfejT/CrhAESD1EkWZYbpW7wgdLrGP3/IEuoo52+tBo1V8F52OAloPS4GkD8AYY6z0F05A6ZJmvRrNNBQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Pu6glnNUu96k7NvxZWx4jhxJ7o3qGLx3GB1OwA1z2S5YcQYq02QRe5FhmyLz1gi0io8I4HRXdV7deacaJkVOAQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "yvua/o2G1xaYalwI33dimtEOZd3dG7uJzYp2EXUWlHCMb7VbdG2U2YrUFJVysg8I2sRivvRsUOY22g3n61cyCw==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "8BR2w571RQ3mDoxpQfvOKhdF6tStGDZHOAq2uLSnGPaE7LXHJku6vgiCIL8mjSjk9gtFYWn5J+D0P39TbijTBw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Cloud variable name." } }, "required": [ "name" ] }, "example": { "name": "download_url" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "name": "download_url" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "APP_VALUE_FOUND", "message": "Request completed.", "data": { "name": "download_url", "value": "https://downloads.example.com/ger/1.4.1.zip" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bbd09cd1436934fbe98638fc3b0c3e3cd9cb7d7f8b4b4d9e5623986401d40bd2\"},\"response\":{\"success\":true,\"code\":\"APP_VALUE_FOUND\",\"message\":\"Request completed.\",\"data\":{\"name\":\"download_url\",\"value\":\"https://downloads.example.com/ger/1.4.1.zip\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Q1pGBWh0Bkm/eq/OBXb8K7Wqdc+OvftAD57oJHVkFLPagvUveFyr/WHND4l+8AaagTTPzODW4T8H5GW3fq58CA==" } } } } ] } }, "/v3/data/set": { "post": { "operationId": "updateAVariable", "summary": "Update a variable", "description": "Updates an existing cloud variable only when Allow remote updates is enabled. Paused variables cannot be changed. The authenticated app determines the scope.", "tags": [ "Cloud Variables" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CloudVariable" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "APP_VALUE_UPDATED", "message": "Request completed.", "data": { "name": "download_url", "value": "https://downloads.example.com/ger/1.4.2.zip" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":true,\"code\":\"APP_VALUE_UPDATED\",\"message\":\"Request completed.\",\"data\":{\"name\":\"download_url\",\"value\":\"https://downloads.example.com/ger/1.4.2.zip\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "IsyfL9ps9PjScaJOfzaivfjZmilExxnwkWuUXVOIQQ9j74BGPOxVRxZOs88IAgacaL9ecfXckWjH1O/qyrOrBg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "euGzW+NmFHAeYCuZ08aBRvstYawqZm4D/TErRT9/RhCCMqa2WNkMYqUxgrFvs6dbYqAud1ceVodORZ1Ad7ZLDQ==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "/47M5qArjs6aB/2E9iPjdmGdSXiMvfi+FBKQmUIoicTmFDhCoRepbVsm5/JL1iDgbIh7prQMrLwLqu+sFMF0DQ==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "GFXzUlwrDZ/USjKXakcIQ/63gJuPBiQzP9U5mnEYCQJr1Qit7hNxViB0gScxIdzuI2fJvCzGk4O32izz/FH6AA==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "KTLjWi51BuXwGfF7pC7BbCDlYz3E0eE4cnpx391y8537oY3//VZE2uTfsJFy7rKoCB3gYxNoCqxQPmsfPl2jDw==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "O+M1+PNjVKLVof2kuQv9/zIpMb1YcT5tqi1rcQLO75kKGy8Lxzc8yOKwTLMESWivWfutb1SiYHtDA3hcMKdBBw==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "XljFeQnYX8X8wfbgyhF2DCwgzm7p+1V1Ks2CKtI5P3542N6wx3CuOwDUt0MwxNwfek1CYQp0hoMFVjTu3oq3DA==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "4I9RWONvCLzPK42ls+N1cWLhlHx5BfMBhfpYDKC/SYiXJr9NDpVSLjqQVOlIohx+ZdJcMvZYR4rHe3PUML9yAg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Zm34n0rpbPhqwy4ojJGMY8LhGeN9D9aQ1r4NEg+yuL4DFh2zDCfp2/qno9Yf6xsvksILygfFyPJNTwv1puClCA==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string", "maxLength": 8192 } }, "required": [ "name", "value" ] }, "example": { "name": "download_url", "value": "en" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "name": "download_url", "value": "en" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "APP_VALUE_UPDATED", "message": "Request completed.", "data": { "name": "download_url", "value": "https://downloads.example.com/ger/1.4.2.zip" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/data/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"bf205c650a218975fcc3cff7b2574b512422ace0f1c2b8f02237a7cc044d3972\"},\"response\":{\"success\":true,\"code\":\"APP_VALUE_UPDATED\",\"message\":\"Request completed.\",\"data\":{\"name\":\"download_url\",\"value\":\"https://downloads.example.com/ger/1.4.2.zip\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "IsyfL9ps9PjScaJOfzaivfjZmilExxnwkWuUXVOIQQ9j74BGPOxVRxZOs88IAgacaL9ecfXckWjH1O/qyrOrBg==" } } } } ] } }, "/v3/scripts/get": { "post": { "operationId": "fetchAScript", "summary": "Fetch a script", "description": "Fetches the named script release, optionally at a specific revision. The SDK verifies script signatures. Fetching a script does not execute it. Distributed scripts are readable by authorized clients and must not contain server secrets.", "tags": [ "Scripts" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "SCRIPT_FOUND", "message": "Request completed.", "data": { "content": "const welcome = \"Welcome to MyApp\";\nreturn welcome;", "manifest": { "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "startup", "revision": 3, "language": "javascript", "sha256": "c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57", "bytes": 51, "publishedAt": "2026-10-24T10:30:00.000Z", "scriptId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "keyId": "5cc558a6d81dbb98", "issuedAt": 1792843200000, "expiresAt": 1792843500000, "minimumRevision": 2, "minimumAppVersion": "1.0.0" }, "signedPayload": "{\"appId\":\"d52d697c-490e-4d0e-bbea-0884f2db409c\",\"name\":\"startup\",\"revision\":3,\"language\":\"javascript\",\"sha256\":\"c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57\",\"bytes\":51,\"publishedAt\":\"2026-10-24T10:30:00.000Z\",\"scriptId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"keyId\":\"5cc558a6d81dbb98\",\"issuedAt\":1792843200000,\"expiresAt\":1792843500000,\"minimumRevision\":2,\"minimumAppVersion\":\"1.0.0\"}", "signature": "AeriwXWFVD/4Ohb+3RLcmQpuEFfDK99yWiLctCmnM7cigXmlMZ41pDnCCDS4/bBZdzgPtk6dX5bbfO+BxNg0BQ==", "algorithm": "Ed25519", "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":true,\"code\":\"SCRIPT_FOUND\",\"message\":\"Request completed.\",\"data\":{\"content\":\"const welcome = \\\"Welcome to MyApp\\\";\\nreturn welcome;\",\"manifest\":{\"appId\":\"d52d697c-490e-4d0e-bbea-0884f2db409c\",\"name\":\"startup\",\"revision\":3,\"language\":\"javascript\",\"sha256\":\"c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57\",\"bytes\":51,\"publishedAt\":\"2026-10-24T10:30:00.000Z\",\"scriptId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"keyId\":\"5cc558a6d81dbb98\",\"issuedAt\":1792843200000,\"expiresAt\":1792843500000,\"minimumRevision\":2,\"minimumAppVersion\":\"1.0.0\"},\"signedPayload\":\"{\\\"appId\\\":\\\"d52d697c-490e-4d0e-bbea-0884f2db409c\\\",\\\"name\\\":\\\"startup\\\",\\\"revision\\\":3,\\\"language\\\":\\\"javascript\\\",\\\"sha256\\\":\\\"c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57\\\",\\\"bytes\\\":51,\\\"publishedAt\\\":\\\"2026-10-24T10:30:00.000Z\\\",\\\"scriptId\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"keyId\\\":\\\"5cc558a6d81dbb98\\\",\\\"issuedAt\\\":1792843200000,\\\"expiresAt\\\":1792843500000,\\\"minimumRevision\\\":2,\\\"minimumAppVersion\\\":\\\"1.0.0\\\"}\",\"signature\":\"AeriwXWFVD/4Ohb+3RLcmQpuEFfDK99yWiLctCmnM7cigXmlMZ41pDnCCDS4/bBZdzgPtk6dX5bbfO+BxNg0BQ==\",\"algorithm\":\"Ed25519\",\"publicKey\":\"-----BEGIN PUBLIC KEY-----\\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\\n-----END PUBLIC KEY-----\\n\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "2k7GwyJJB2tcKWbCRDUivMJYQ60q58SYIp3JWimbzz8oFcVCTxOATjiVkq4NgxNNoOCwq251zHEOhm9+GhycAg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "J17XspFOdv6xqQ8Itsf08Ilq0urK4f/wf/ACSzflGpHCcInjIztkeAM65/jVL/J6v8q8e+cXpvoX0rEri6vbDw==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "O3ZTWENGGVK05Xd+XamZgUZY/DZQ5eMgqU54mQya7C8JSTJ/kGqIp0IBaKjiWcQEd/1Xy4VMKwvS5dP4xxSZCA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Txq+JfTR5lTGstwes/6xgcnrM2Kq84KfdFkpRdl4IS9bByGS12mlIjSw51ADSE+YdAwhB6AjK/Vdi6vGQxNbAQ==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "59N54S4BDPHHyz3EiZ+qLXx929xa6GyhuzDJA+09lwN46pw/mkixO5DtNua1V/7Wlip3JBu4M8wmYOSDv8n4Cg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "yUmElER0JMUWBPAXI1wTlg+qePRFTPmQ717dawvJHfPgiUmekYQmSuNWFT3JKyMoastlO0/g6aFV3Fp8JCowDQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "+i+xx8/3uX0HZSUm2c5zE7M08+xkovEoGawAiMChISCEn7W+w8+OvT9/eKMTTqLax2HU2odXd3XzfrZCGOTOAQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "H+B5wSAfa5Zt8suVGQJujItWVBFYVtVbjUZZmAMXIxqg8XpD7nL2QZeP/7sCRIxjI3aAKsIxCqlXOdCMHZ7tAA==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "WjwzEJSITOSt1BRLTSjDyQuRX5wkHDME1tiJWJdFEWaLVQXkgr/u26FXPEFMXq/+bSDOFodUcHmCwLEGpJCoDQ==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Published script name." }, "revision": { "type": "integer", "minimum": 1, "description": "Optional positive revision number. Omit to request the current published revision." } }, "required": [ "name" ] }, "example": { "name": "startup", "revision": 3 } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "name": "startup", "revision": 3 }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "SCRIPT_FOUND", "message": "Request completed.", "data": { "content": "const welcome = \"Welcome to MyApp\";\nreturn welcome;", "manifest": { "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "startup", "revision": 3, "language": "javascript", "sha256": "c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57", "bytes": 51, "publishedAt": "2026-10-24T10:30:00.000Z", "scriptId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "keyId": "5cc558a6d81dbb98", "issuedAt": 1792843200000, "expiresAt": 1792843500000, "minimumRevision": 2, "minimumAppVersion": "1.0.0" }, "signedPayload": "{\"appId\":\"d52d697c-490e-4d0e-bbea-0884f2db409c\",\"name\":\"startup\",\"revision\":3,\"language\":\"javascript\",\"sha256\":\"c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57\",\"bytes\":51,\"publishedAt\":\"2026-10-24T10:30:00.000Z\",\"scriptId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"keyId\":\"5cc558a6d81dbb98\",\"issuedAt\":1792843200000,\"expiresAt\":1792843500000,\"minimumRevision\":2,\"minimumAppVersion\":\"1.0.0\"}", "signature": "AeriwXWFVD/4Ohb+3RLcmQpuEFfDK99yWiLctCmnM7cigXmlMZ41pDnCCDS4/bBZdzgPtk6dX5bbfO+BxNg0BQ==", "algorithm": "Ed25519", "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/scripts/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e5618de609632632922670eb1cb3d55e1e5387dcf6481e5087899fc8769bb495\"},\"response\":{\"success\":true,\"code\":\"SCRIPT_FOUND\",\"message\":\"Request completed.\",\"data\":{\"content\":\"const welcome = \\\"Welcome to MyApp\\\";\\nreturn welcome;\",\"manifest\":{\"appId\":\"d52d697c-490e-4d0e-bbea-0884f2db409c\",\"name\":\"startup\",\"revision\":3,\"language\":\"javascript\",\"sha256\":\"c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57\",\"bytes\":51,\"publishedAt\":\"2026-10-24T10:30:00.000Z\",\"scriptId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\",\"keyId\":\"5cc558a6d81dbb98\",\"issuedAt\":1792843200000,\"expiresAt\":1792843500000,\"minimumRevision\":2,\"minimumAppVersion\":\"1.0.0\"},\"signedPayload\":\"{\\\"appId\\\":\\\"d52d697c-490e-4d0e-bbea-0884f2db409c\\\",\\\"name\\\":\\\"startup\\\",\\\"revision\\\":3,\\\"language\\\":\\\"javascript\\\",\\\"sha256\\\":\\\"c5abdd7519b43a85adf9187a92ad12fe2eaae7b7dbd3aa981201a318c9599d57\\\",\\\"bytes\\\":51,\\\"publishedAt\\\":\\\"2026-10-24T10:30:00.000Z\\\",\\\"scriptId\\\":\\\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\\\",\\\"keyId\\\":\\\"5cc558a6d81dbb98\\\",\\\"issuedAt\\\":1792843200000,\\\"expiresAt\\\":1792843500000,\\\"minimumRevision\\\":2,\\\"minimumAppVersion\\\":\\\"1.0.0\\\"}\",\"signature\":\"AeriwXWFVD/4Ohb+3RLcmQpuEFfDK99yWiLctCmnM7cigXmlMZ41pDnCCDS4/bBZdzgPtk6dX5bbfO+BxNg0BQ==\",\"algorithm\":\"Ed25519\",\"publicKey\":\"-----BEGIN PUBLIC KEY-----\\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\\n-----END PUBLIC KEY-----\\n\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "2k7GwyJJB2tcKWbCRDUivMJYQ60q58SYIp3JWimbzz8oFcVCTxOATjiVkq4NgxNNoOCwq251zHEOhm9+GhycAg==" } } } } ] } }, "/v3/features/list": { "post": { "operationId": "getAllFeatures", "summary": "Get all features", "description": "Returns the effective feature values for this identity. Requires Plus or Elite.", "tags": [ "Features" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "features": { "exportPdf": true, "videoQuality": "4K", "projects": 25 } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"features\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Lz4Ogi8hge7IGj6IrBP79Es3A7bRhnzma8v2r+OAl9p20HkUpUgZgeIwwYKenIey3O4rvfFAcpCnvH74SkvTDw==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "jYdIPaxbuNUv9yDtpqrnm7VGvN0YQMp/2moScIAcrsAQsHRH2AYU2qm9goTkZ1FgPRZAZnOH54BWo6ssa/3LBg==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "dfKc5IRf0/BfudvrGnllaL8VzPuKc8Nffx00PfjqbaSxoZuMlsQ/I4lYRKXBiPNazUqebqVDQQnbdYzHMLaFBw==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "PZLBZnrpbIE1yUKzA57NZ0Wwr7io7WiIb4kzApYTO3kC2o9dfBjwe8DcVMZOtzA8zpAbeFdD2K3/sKO7FrYoAg==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "fHnnCHwdgNzi8lgluhPr/t1k5I41AzE2oBFa3Yy5d4ZF8crSJp7SCA5R+vv/nweOWJtxBqrWCk1Yrgk2UMOTAw==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "QAB8toAsdXebaqguotg0C0GdeFy/HPFHCNBXmCQU3wJHMNyfQRuueVCh4OvUi092BfByl6cSzK7m7JUbIDZICA==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "iZJICIS9IpcGNNwmeofsQOw+r9V+grjMvCgvCll7wypZydhJ6+O5wTiDQOMC2bJUb5wlAfP0VFWSZUF7HykCCg==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Dplon2r90vfXddJkmsl595tkAVX6tSMsKSJ2wI9BaexJ0tVrry/7Is83zR/YRSnkAC1SieCENYBT8qQRx5p2Aw==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "lHwv+ZHsYB9YbX6OBbiS8xPaGYk77DL5j9tJ1oFfpcth3nwKVEREXd/3JA1Bj0S4O+B+4yyYrNHw3EbMRqdqAw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": {} } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": {}, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "features": { "exportPdf": true, "videoQuality": "4K", "projects": 25 } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"features\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Lz4Ogi8hge7IGj6IrBP79Es3A7bRhnzma8v2r+OAl9p20HkUpUgZgeIwwYKenIey3O4rvfFAcpCnvH74SkvTDw==" } } } } ] } }, "/v3/features/get": { "post": { "operationId": "getFeatureValue", "summary": "Get feature value", "description": "Reads one effective value for the signed-in identity. Features require Plus or Elite; metadata requires Elite.", "tags": [ "Features" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "name": "videoQuality", "value": "4K" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"name\":\"videoQuality\",\"value\":\"4K\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "139FQIG1jvlZDlr4cl81jkYl5/5cB25jJG9aVR82onWzkNnY23IeacHTg/A6Lj67aMIDUuXOvCK0KI5kd2JdDA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "XtKqT6fH8Cu30nufWd2GGCmA9j4Y5ne0RNmuRtWxTu0ZIu6ZiAcx+qidhmXmK/mrZ8uA7h4cfx8YtXud4fNSCQ==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "yk3WX+D+UMcXV7aYC69tH6NJpn77DfDZI1zjCjrJcwmVQpxV6+h4s/rygSMho80llYb/4pK809LpXHB5xxVLAg==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "5gkkRJUqxQuthfDS2TcHW6zXH2PfL35M5RBGnXYMgUFCiyH+ZtgdOIMFAlL/fI7qvoOZfm04xBA6Ze0Sy89ZAQ==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "GQa1g/JL0W1dcATvzDFjxEtNwh3ZmS2X61Jf2OWoViS7Zg5FVgWCSfOhHmqNJPQEGKpYoDWefeTXpm3FxDnfBA==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "+EJAGBnLOHk39dtov7kx32+ylVCP3p+L9M6BbCT9jdp13fx62AFelUAkgKfA6CC67HxQKRfLHCJzWJnAXZP4AQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "unRkACtN8tBddJXHPDjC4MFm9hH3JEOZo2zTWEnLVFNOgv2fRNK68VMoTq9tJQ+dGqzr1li7Zu/b6FYz6jw+Bg==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "wg9n550nrpX7Uo1fe3jfk0mCq+Tq6b2ns1aBj1hLEnmfBnwtyCJRhGPWjxuFLYPZNrhpNl91sqJKGgr1UMNAAg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "AxEcqruuwEnjhbCMW9kv87sDeb9jiJeWw1LDxBOt3MgADgGZ80BVPs1qbZzBGBTkQakagRszKCXsoPHF/+70AQ==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "example": { "name": "videoQuality" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "name": "videoQuality" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "name": "videoQuality", "value": "4K" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"aeb1ba9ab6d53fc312874b759ac34c227c6eb263cd59e272490aceec37bd92ce\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"name\":\"videoQuality\",\"value\":\"4K\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "139FQIG1jvlZDlr4cl81jkYl5/5cB25jJG9aVR82onWzkNnY23IeacHTg/A6Lj67aMIDUuXOvCK0KI5kd2JdDA==" } } } } ] } }, "/v3/features/check": { "post": { "operationId": "checkFeature", "summary": "Check feature", "description": "Returns enabled=true only for an enabled Bool feature whose effective value is true. Missing, disabled or non-Bool features return enabled=false. Requires Plus or Elite.", "tags": [ "Features" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "name": "exportPdf", "enabled": true }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"name\":\"exportPdf\",\"enabled\":true},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "hfYpAjWvhogKKzcpDkhPQMM2WKYrT2Aag60bohSlofp7FrBqDg8cLDDqoBSuER34IXUPKxkgi+3DhRYhI0tBCw==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "uBo6bao9dr2cdAufgICgZqikCNgFawJ+t6R/lf6ulhyO/o+jVzMqDczqgoeckjNwoJg4Ld9XGquysMzOfHjwCA==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "AuCp3pn6tp1PNoddUhLFFo4kEX0DAultd0V6r8CNEk7/MoCLwl2ZGSql9gay9AoYNtorOY9u1msEW3V9qsXmDQ==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "1m4WNQaibpIz5TBt7iiamJWv7Lm9pd6Q7oGTCsMQD36bWmgGfL0ZDTo6Hivkkr1sxqAA9bABmDydnFpcbwZxCA==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "nnhqI1RW5HiZ87rgrBxNtJIReoWVKnnmCgHUCQOXIcyiv9wdkLlFSqwFXcCkOTfSwqmRbOhwhzh/uIFowVEmCA==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "hAqgKCibU9/U9hPO62W4XGu5G+OY4krrJHelEBCvSN0MpQngmmDMR3rM1MAsK+qSBzIhf0LWW73KERJUEWMTBQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "9DutscOdj/GqjssrC7oLBFNozypbX+T8KdsOlGBGHaINWVXJJ0YWOFBhx3AOfk1HXTEXgIFN4adQR1Gl3smKAw==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "TcNf1HGnK9+iY0aCSrYbMfu0XiEhrS1aFbAycNtAzmmXsY+2U2ti2bdgMwZv0qXbj04lFNU+sXE2WbLB2PasDQ==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "3ulN9NIliRX1z09YNDIT1GzkZN7/tfMTx11TQTwC/ShZF2L7yyquPm2Qf5TOgxHSPwK7+0CiITAHV2gkHjB/AQ==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Feature name defined by the developer." } }, "required": [ "name" ] }, "example": { "name": "exportPdf" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "name": "exportPdf" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "name": "exportPdf", "enabled": true }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/features/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"9691303086c5986ccf73fd7a75bcc850a24ed6ed824f237246950bccc9e973a4\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"name\":\"exportPdf\",\"enabled\":true},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "hfYpAjWvhogKKzcpDkhPQMM2WKYrT2Aag60bohSlofp7FrBqDg8cLDDqoBSuER34IXUPKxkgi+3DhRYhI0tBCw==" } } } } ] } }, "/v3/metadata/list": { "post": { "operationId": "getAllMetadata", "summary": "Get all metadata", "description": "Returns app-readable metadata for this identity. Private fields are excluded. Requires Elite.", "tags": [ "Metadata" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "m99yWHEP4PQceKXlorZAM7IPBnLjvVzQWQF+c7NShSbp4iPanOdT2qOpujZAdm2lZVqZMXxrM2SX5pg45sKaAA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "iEmY48cbhtYOPjZlpGr7DaTwVBli9hdvVMSIXSp8ai3rAt25uG7qmTUnA1RNNHDl5CWSzrgOQqsgmJrSbe1RBA==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "JZe6TEpvPd5IMY9lBcSDROMvZoUsrZUycJZ8a6/9e68u4FLpZe+WGB/BO3W7fdwrqOpe5IYYX7UrSmi183uJAA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "KpR46eh7Nl1Tcx9YoPGvQHFDddB6JzGyl5YxRLxIVvDBhiVjismPZk6kxxIpiSxO4cv0uRCWtqVUPlxSW/D0Aw==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "ItKlcvHfkNLA/9vLtVTJ8XoIijRW2A7JW6COqx4k1FlRbC+suhO/ywPxGihqK9SOYAFHd/+t8ibQ7WfeuBXrBQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "vhKpXozdKgutJt9Z2302pmH81qqibAUwCbjFBjMPNJVjRtN0kzPqd4ZjabXDTGDYd0AV3BUtOOzDjuosmKDwCg==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Tc7j885V3oaPMMEM2Y2gExkWm/vSqZcmSdh8mra7I0YCcypXGtYoBR9MGyB53K2iK96xjLiBMIDNgF158n45CA==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "jLCzTCaU75ccnJxvVuzM+542I4Qjbpll1Kur11O+csr3r2FXnE90IM/Z7q1aakqLy9gHNxxC7u5I3j+0u/hDBw==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "xmMcqyYhGnRkv474agnDJFiynY8/YzNGpwDR8hOSUfl3yHMO0AOnxhyHwBmMCnWOb+i06KuKaIcGCQrSERPZAg==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": {} } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": {}, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/list\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "m99yWHEP4PQceKXlorZAM7IPBnLjvVzQWQF+c7NShSbp4iPanOdT2qOpujZAdm2lZVqZMXxrM2SX5pg45sKaAA==" } } } } ] } }, "/v3/metadata/get": { "post": { "operationId": "getMetadataValue", "summary": "Get metadata value", "description": "Reads one effective value for the signed-in identity. Features require Plus or Elite; metadata requires Elite.", "tags": [ "Metadata" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "key": "preferredLanguage", "value": "en" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"key\":\"preferredLanguage\",\"value\":\"en\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "oBrEUgpEtDy9J/RuO5O+4KgS9eHxgFJsEUXiSNeE/4Z+cZIV1WPxl0U0QaRsLrt9jqm+2WW6n4x4TvSD31zfDg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "oICndaiYoH+0qyQjWfqE0oucgh2HSFtAlomThoUz+8rsOXeiTf0oeedoNL1r8oLvs5QSZuG/VEVByNU8OGndAg==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "jvmQxLoLp4oC5rLMMMcrgxXrEvnPs702XKPOmTpHle4iGTYcs+hi2A1Hz1TTTA2Cjq8pEAikRvZTNVyn2X5KCQ==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "fA3RAUooSxjXU94bmRMZheFt991n77bKJMGvfGtGhXbYzA+Bo487GnVe1JNmC2mGw5KYyN/lch1C3/fnW0ajCQ==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "n7m29ea6eGAAZxxjHrkzJceocc/UwMKy9ULDPEVAeBCoYanjDFEKYzwDAOiGT+se3iZRlgmKnrdneNz8rIC4DQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "jv1q5zmvkHY78BmFsx+UJQR2tLADPSaqg2iYmCkVvBYrCUd2tpdhWHmJ7YA9mlR2HB0bMEOqQmASUehJC337Bg==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "u8g1SWUldGfFEC2TCUR0296UqjziAtRXsMi3ZRMj4nmHfW+NkUDmcgr60I8jhLZtD7nIDrxSXDuaoZcO9RTGDw==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "37Ul19h7Q2QELhhYJYi5AuiUpBdktdFKnNC34qVm/aBXuhsvZVtpDea4dcyUzXDaCNIJ7hUoR/pSrmyi6wlMDw==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "9IpidCWZD8Bpr/gGuvRNYT236Gxb8RcCU6wsj16baS5iwSa7MbCn++xIfSFUJgjKb1dEl7rK05tQfQgGb2ysBQ==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] }, "example": { "key": "preferredLanguage" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "key": "preferredLanguage" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "key": "preferredLanguage", "value": "en" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/get\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"a61437d4b7ec072e820436ca3ff7820cc65ea08db9eae08850c04c41eef6fd0f\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"key\":\"preferredLanguage\",\"value\":\"en\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "oBrEUgpEtDy9J/RuO5O+4KgS9eHxgFJsEUXiSNeE/4Z+cZIV1WPxl0U0QaRsLrt9jqm+2WW6n4x4TvSD31zfDg==" } } } } ] } }, "/v3/metadata/set": { "post": { "operationId": "updateMetadata", "summary": "Update metadata", "description": "Updates an existing SDK-visible field that the developer explicitly marked writable on this identity. Requires Elite. Cannot create fields, write private fields or change inherited plan defaults.", "tags": [ "Metadata" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IdentityAccess" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "q//BzgNvUaxLwtmBOUa8nT4GV/fXcTTrMoxBMDmXUBziilqp/bKC4ktb5K3d7ISy9ZT42x1Y7eExm+J3DwhxDQ==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "uClQecn8geRxV3ruRwZztNAab1pYZ1N2SRdL9/6jrz1ZE6CJqtNtQJZS2YYYww0xXObfAq/VC71Qw+JElY2WBg==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "KSeRtwJEM+Ns64P/f/YHJVCh6SnJnxWU6NrZd1sZkBEh31saKfzCzAEQ/Oi4wU77XYioGOFa1Z7IUlR4PWQRAw==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "t1JkMplbtekXXs+koAojyNwqwytkmjd+kpdnf/G83KD2PHqQjdxOQPcI8izKE+K+BiHLKiaLRZE4dWr2DNduDw==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "0V00R/004lY+m+gDJJsL76MlwbJ6TDLOQ3qJiREzOVd9Pgr6XzqRGSgShtX0w/e51vkE8kuNeZ4pI+mnGftoCQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "yguAlG+/nD0+AdqV4PjIRxRDi5mFUX18fk4glanA5X4oljN+o4o01T6bzaFwXa7TGX2sSXvbpCQFeQdeLA0KBw==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Nz/a/8re+/jGwVRx3Ts7JD5Wq/7Wa1Xl0hglrXVJQyJwCNV5ZH52JL7bEmQTNR7wkuwvyAsSGMIpwhzKBouADA==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "JkAMn6z6Fq+ZZUFNDbKURdB7/xxPEX4zv4o7qv3oad+eWEOfDcRkvceHJYPKUQxvg1KQBtcooI6/w9cldqlfDg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "nHuKacRd/mDmXnxbriz+lEuxiD+55djR6tMH2EYXoICFErgCMIbxu4TzjXRg76E31m/AQ27MMgJFIEI9vB4aDg==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Existing metadata field name marked writable by the developer." }, "value": { "oneOf": [ { "type": "string", "maxLength": 4096 }, { "type": "number" }, { "type": "boolean" }, { "type": "string", "nullable": true, "enum": [ null ] } ], "description": "New scalar value. Allowed types are string, number, boolean and null." } }, "required": [ "key", "value" ] }, "example": { "key": "preferredLanguage", "value": "en" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "key": "preferredLanguage", "value": "en" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "features": [ "exportPdf" ], "featureValues": { "exportPdf": true, "videoQuality": "4K", "projects": 25 }, "metadata": { "preferredLanguage": "en", "customerReference": "ORDER-1042" } }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/set\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"094354e9506aa3735ab497051b17cd1c3e3cfb2cf5eb34ae96b503c8e3f7ea0c\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"features\":[\"exportPdf\"],\"featureValues\":{\"exportPdf\":true,\"videoQuality\":\"4K\",\"projects\":25},\"metadata\":{\"preferredLanguage\":\"en\",\"customerReference\":\"ORDER-1042\"}},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "q//BzgNvUaxLwtmBOUa8nT4GV/fXcTTrMoxBMDmXUBziilqp/bKC4ktb5K3d7ISy9ZT42x1Y7eExm+J3DwhxDQ==" } } } } ] } }, "/v3/metadata/check": { "post": { "operationId": "checkMetadata", "summary": "Check metadata", "description": "Returns enabled=true only when the app-readable field exists and its value is Bool true. Requires Elite.", "tags": [ "Metadata" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "key": "emailVerified", "enabled": true }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"key\":\"emailVerified\",\"enabled\":true},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "eouekrDA8T6r/69RZoC3bvXBiyB5UraOGXgyBME5TP/G4gax+A59hPimM3owY/qerbIkmIR6/Z+xPx78ylshCg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Q3Y7vm+HkbVJ6E72ZXdaRmlMCglHfEIm91o2c4Dtl9tdQ+TrbBHn4qIwDjeZ2Tp72kmKs4E+eBGGxDdeR8GMCw==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "LEXvoeULj/O3w2lIz3kbcIVIvFVvK5+4qvGiM0Oulw1SMzVfgFRpofr/SebJxHQZ4RljTJ315DxiBUePA56RDQ==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "QaoXBzMDhG0XWRqq01JNg/ljaEZksF0PJc5JfqxTTQjx0QV2WxIxZ5Qn3yBXjL+wIgjYw9DbzMPPazcsaZ/wDA==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "GQ31wMoF7lIMJZjCn3slZ95clAZNBJJP8acLAleUiFtMUDZmAi7s0SvYv4cR9Px1WPqlr5pRB/jMbMp0YYSACQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "kUB1bYzZoslx6moEqu35N5EMf1qOtJNwebFCnRZRukoVcjo0pVlU4iunAKTiXmiZBuL1bX+sV6Osvjq7zJ6OBg==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "BFCe5rl28bGk5tA4HmrWw3Rju+Xz5s5s/aThl8y/Bjrrj0hKaKvt7XSd/1vDJJTaeVV32Xn9pbmkhzVe4jwiCw==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "rtgxgU7VP3TF0lPLX3k7s0lzt/5M0ZtJ/Qmpvs3jnZFpCG2hV7XPTMedQDafTZXlHks9gSAqesKPjk6lMeyxDg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "zkANgyXeaf2OhKTwbntFBGaY7tmpCzTVxO+ERR6eDJGpfjowwLYwR/UIlbvCjOk01fHSNnSLtqV5svQpcAZOCg==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] }, "example": { "key": "emailVerified" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "key": "emailVerified" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "IDENTITY_DATA_FOUND", "message": "Request completed.", "data": { "key": "emailVerified", "enabled": true }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/metadata/check\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"689eed79758046efdbfdb27197d4fc26aa4803c7a2458fa32c79d77ab20b3acc\"},\"response\":{\"success\":true,\"code\":\"IDENTITY_DATA_FOUND\",\"message\":\"Request completed.\",\"data\":{\"key\":\"emailVerified\",\"enabled\":true},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "eouekrDA8T6r/69RZoC3bvXBiyB5UraOGXgyBME5TP/G4gax+A59hPimM3owY/qerbIkmIR6/Z+xPx78ylshCg==" } } } } ] } }, "/v3/webhooks/send": { "post": { "operationId": "sendWebhook", "summary": "Send webhook", "description": "Send text or JSON data to the webhooks enabled for this event in your dashboard. The webhook URL stays on AuthlyX. Requires Plus or Elite.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "WEBHOOK_QUEUED", "message": "Webhook queued.", "data": { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":true,\"code\":\"WEBHOOK_QUEUED\",\"message\":\"Webhook queued.\",\"data\":{\"id\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "wWwd9kAt33vGy3jQxM9gxsc19H4SdD/e7HBokRg6yiiU4qkeOiqq4bikIYrxgYjOSitT+KZ+SNuKhx7TCEpcCg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "akxKoy0QMcyUroQj4CJE2XJol7oskpDjG8/SYq7I5kWAzdb31bnfk3wRYTuGFuEwjOVYN5GUlOxXm5BxlFRECw==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "sk62k1XAY6L0HaT6bFzPsnwUWFeYi/M7t1QZ62c+ASFVOwmZiBA9obDF/ZP7YTj6S7sCJHXPMOx749sSput2AA==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "tElnb1N/X52hyi92wlX9uYHIa+1o5QTM7XsbKH7trL07OI82ncqLupdBHL8QsLoLrjEY/t1RjoaX0IbPvMKXDQ==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "rsY9bU/LGcBojgAbyxvHB487QnYuo4clwxL2pJy7G4tMs1l49j/MEbKBBGe1Gq+E+jym5LxQDBzEy+CdU2HaDA==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "qaLGC8Ne6Sf2GlLOwOTyNoK+KA3316q8Xbil4F4wuMHz9bs2kDPvrX2ngb5tTDRvC5jgxXy7ZMMs6DhVxljXBA==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "n7X8F5mwYrLzkbDih8VhTB06E+uXz3V/guE9/jRQpvciylstWKZpuMfcViMiLI/Tduqd1Wy/1pjvF97Ugm8dAg==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "CQ9UUNk3H/nVX9eiOgwalPPj9eUxg8zcSPXcOtClMU3ElFjZtNOKoP9u/f2qaa6BHwdvVfiwVQagZPM/qubWBQ==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "L3PW4XQZNWvodZDKi6frIUaEP8D6WuIppJYqtWmUK6voKFZQysKv36Y7PZPDn3I1peBBWffMA/+wYilrGZPqCw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$" }, "message": { "type": "string", "maxLength": 2000 }, "data": { "type": "object", "additionalProperties": true }, "idempotencyKey": { "type": "string", "maxLength": 100 } }, "required": [ "event" ] }, "example": { "event": "report.exported", "message": "Alex exported the monthly report.", "data": { "reportId": "REPORT-1042", "format": "pdf" }, "idempotencyKey": "export-1042" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "event": "report.exported", "message": "Alex exported the monthly report.", "data": { "reportId": "REPORT-1042", "format": "pdf" }, "idempotencyKey": "export-1042" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "WEBHOOK_QUEUED", "message": "Webhook queued.", "data": { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/webhooks/send\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"867625226ed3e3b1baac5ce334c4b13fb1b5addba01ce62ec122a500d6856818\"},\"response\":{\"success\":true,\"code\":\"WEBHOOK_QUEUED\",\"message\":\"Webhook queued.\",\"data\":{\"id\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "wWwd9kAt33vGy3jQxM9gxsc19H4SdD/e7HBokRg6yiiU4qkeOiqq4bikIYrxgYjOSitT+KZ+SNuKhx7TCEpcCg==" } } } } ] } }, "/v3/logs/add": { "post": { "operationId": "sendLog", "summary": "Send log", "description": "Adds a developer-defined message to the signed-in application App logs. Plan limits apply. Do not include credentials or private customer content. These are separate from dashboard audit events.", "tags": [ "Logs" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedLog" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "LOG_ADDED", "message": "Request completed.", "data": { "id": "1042", "webhookQueued": true }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":true,\"code\":\"LOG_ADDED\",\"message\":\"Request completed.\",\"data\":{\"id\":\"1042\",\"webhookQueued\":true},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "AczRlNKwSgzJ47o0fIGjlL0rjnzcNC0hs7mGROVMbBVUFilK4/H6DoDwZH5c2yZPUbC49ZR6nrJ0GHprmvtvCA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "YgDiEqnJydeEIL0d+si1YvGp4k/xk5KvfnLQqB1xGu6oxijYexZFpa91lNHAMNqgXnzqXN31gQujW6YmcRYGCQ==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "rXU9KJV1Xiq3XU/OoMy0jb9zvAv2M1XfOJiQuVIsuiccUAOkypCtu/mNP54VyygjaNIj6D5ZwrL7IpW4p+URDQ==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "dFEWoBocWaMVE2CumIyrepyAaVfkXnmXOcEaVjyfq7/tSMh9raj5u3x4XtkdE4bHt7APn9eElUGOVOUZ7egmDQ==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "VJeIq9yHYLKgmxwKFKcmCrTNlPCfo0uLky04W5Vu1wEUET1WmKwLP/1Xz8HQPzUXj3kmeqFNwWRBsWddg92nBg==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "fBCQnkdvj5kMGwvIE87d/zwBmmNqyXjEhd2Ey6ajeaa8qs6vgY+NPo0OHdAfpW41wUOTYjKWoupKdyYw+LprCA==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "wbMgrOfGlUNI+4s8oUieaAoj+mxx2xp+WnxA3LwON/GuqrMAMAJRarPjHXM9LWoTscG0TyaPQYZWNWD5IYJXCg==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "h/BtQHviMafF++7xyEMdOVxGjuvFbKgfm6mT6t8AfYKERY1HlZpymoeXFq+2Zvn8JUYrfjD3k/Ur5e67W/bFDQ==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "HT/OIVR+KN+sHhm7xVYw36bZr+TC5D3Ba8Y4n2sZQ2DhxrqGsvgpASqWHpa12ZsMlGl3XGtQAqfX1JXyMRupDg==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "message" ] }, "example": { "message": "License verified. Application started." } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "message": "License verified. Application started." }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "LOG_ADDED", "message": "Request completed.", "data": { "id": "1042", "webhookQueued": true }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/logs/add\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"e8cdb19cc37867ea4d61b533f953a6d42e19082cec1f7ce59ab1ae5f6c374644\"},\"response\":{\"success\":true,\"code\":\"LOG_ADDED\",\"message\":\"Request completed.\",\"data\":{\"id\":\"1042\",\"webhookQueued\":true},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "AczRlNKwSgzJ47o0fIGjlL0rjnzcNC0hs7mGROVMbBVUFilK4/H6DoDwZH5c2yZPUbC49ZR6nrJ0GHprmvtvCA==" } } } } ] } }, "/v3/account/password": { "post": { "operationId": "changePassword", "summary": "Change password", "description": "Changes the signed-in app user password after checking the current password. License-only and device-only sessions cannot change an app account password. This does not change the developer dashboard password.", "tags": [ "Account" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "PASSWORD_CHANGED", "message": "Request completed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":true,\"code\":\"PASSWORD_CHANGED\",\"message\":\"Request completed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "83GnTRy+ox4w0OIV7fR+pWResCjGgAc0qLh0KojO9Yg/13dhzTVZcDWPsiza605tdf5iY7vU1KaEkM2wMe1FCg==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "SnEtTPrfxNSo7NEK6ESrrPWr+sxI6WWm/zEpRumvj0Islb9khson7wOxhJy07FQwuF+EY6lV/RRhjHHT/biDBQ==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "bIZilHqvkhYPQ4GY9xoAV1skro/4P4seBJOufATYaj54ECAwdLdFE1KhIvpjI3ym3kXwa1currQ5XHytTCcPDw==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "5PLZuzXoh2zBmX7r6pPMu6iU6IARVYoDuoZmwh+hK/69eshDARqIPGXY1eKPY8rdcsmIlsSoCVt3TGoxb6FMCA==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "pWahfI5eDm7iYHXUJudl9enlJ/c5wP7Pq71TOsWlXESSr5xX75qyEy2oN62JMWOYmO6hpueFRki7iVMtSN1YCw==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "igNJ0zeWbNkttr35vFYwLGeVW3H3KevR4GiDWdIo+KSNBklhgX8Vu9i4jKQ/M/3PY8XaGiBaiAcyGAZZg52FAA==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Dncd3B2yYzHxpFcUq0w70+ucJpUdBSmrsqxOOeY6Rck6IaExzc3qUwEeyHyI5GrUfxr3TsPe8W4mu/MoDrARCQ==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "hHI8B9qOUhVR5vV6fuLFKxSAlK5kOsGsIQhW1gCUYWgl7P906t2dw9ulHdjzpBS7tS1qqS+F7WEiDM4oaZCyDQ==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "lQ+/lOm6TEdjWwR8TGQmFTqgeSQbZUYpAK96JuCVG8OHrf/zKB9yrRjNnOAQEuZHc0g7VjyoTas+mvvnZj5IAw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "description": "Current password of the signed-in app user." }, "newPassword": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Replacement app password, between 1 and 256 characters." } }, "required": [ "currentPassword", "newPassword" ] }, "example": { "currentPassword": "River-Glass-29", "newPassword": "Maple-River-42" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "currentPassword": "River-Glass-29", "newPassword": "Maple-River-42" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "PASSWORD_CHANGED", "message": "Request completed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/account/password\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"fec397a514f0a8ed7a2b35b8743dd586e333d2a4ee74349e48daa667d1dc1f3d\"},\"response\":{\"success\":true,\"code\":\"PASSWORD_CHANGED\",\"message\":\"Request completed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "83GnTRy+ox4w0OIV7fR+pWResCjGgAc0qLh0KojO9Yg/13dhzTVZcDWPsiza605tdf5iY7vU1KaEkM2wMe1FCg==" } } } } ] } }, "/v3/licenses/redeem": { "post": { "operationId": "redeemLicense", "summary": "Redeem license", "description": "Redeems an eligible unused license from the same application for the signed-in app user. The server applies plan and expiry rules and links the license. A device or license-only session cannot redeem on behalf of another user.", "tags": [ "Account" ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SignedResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RedeemedLicense" } }, "required": [] } ] }, "examples": { "Successful": { "summary": "Successful", "value": { "success": true, "code": "LICENSE_REDEEMED", "message": "Request completed.", "data": { "expiry": "2026-12-24T12:00:00.000Z", "plan": "Premium" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":true,\"code\":\"LICENSE_REDEEMED\",\"message\":\"Request completed.\",\"data\":{\"expiry\":\"2026-12-24T12:00:00.000Z\",\"plan\":\"Premium\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "7+fAUaV6x/KXqhQZ7wdW0oSxlRGce6JBl7ysG/ETFP7Qk57XQg8uKbZ8zAYlmQz06gR82v3VMbGp4bvHFfDdCA==" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "success": false, "code": "INVALID_REQUEST", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":400,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"INVALID_REQUEST\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "cRogMXARo+rdbkobhB3c7qclo4NBRqTb45J9id3T6d3E2b6B/an2U0tYX2Eq/gJ/fFMjJlqn+RvSZPX58tzqCg==" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "success": false, "code": "INVALID_CREDENTIALS", "message": "Your credentials or session are invalid.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":401,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"INVALID_CREDENTIALS\",\"message\":\"Your credentials or session are invalid.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "Czn5EgrISp9ArJyQOXCr8v5yyV1UxNWtYv9Y6XyU72vbOHpfkvM9JJ2o7fhIgVOOSui3bcrPnB60xQs0yMo8Dg==" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "success": false, "code": "ACCESS_REVOKED", "message": "Access is not allowed.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":403,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"ACCESS_REVOKED\",\"message\":\"Access is not allowed.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "NFE1ljRvQaY2fNXCp0pBRsCfoHUfWgj/vlcoYrhkNB3rOXZIWWU9yPi160ylzJFi/vYS7Zo9f+gv+YcuOKegCw==" } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Not found": { "summary": "Not found", "value": { "success": false, "code": "NOT_FOUND", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":404,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"NOT_FOUND\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "/rcgObRrVJaeXK94iOlKUzsKxqBp+EMCky5xOzJNrE9dA748GIEfPpArAe2WdE3BfDkF31KjoRSfwDeg3uVeBQ==" } } } } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Payload too large": { "summary": "Payload too large", "value": { "success": false, "code": "PAYLOAD_TOO_LARGE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":413,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"PAYLOAD_TOO_LARGE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "O5gsBQ8RXwMysk63JbWsC6aZeA9J68OJ7H9koQlDeP6Z/KSjkobYsa8Pu5L6MNyRuyNeDQ1Y3O82udbg8hYOCQ==" } } } } } } }, "415": { "description": "Unsupported content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Unsupported content type": { "summary": "Unsupported content type", "value": { "success": false, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":415,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"UNSUPPORTED_MEDIA_TYPE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "1EvR/N2FjUyeZQP8yb/4Lwh1l4A9vM5C6IzNuUTlRQz8cVtkO5MDvjSLj78vt2/CffQyoRoyCMTZCC2ec8liCw==" } } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "success": false, "code": "RATE_LIMITED", "message": "Too many requests. Try again shortly.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":429,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"RATE_LIMITED\",\"message\":\"Too many requests. Try again shortly.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "8PdeN5FYBGTd1t4OpTpJSYt1K7isX489tVg/vsW2bY1P+10HQzA+LzPy4Ou3j6gkjNeU9LmO4dYuQNXILaVwDg==" } } } } } }, "headers": { "Retry-After": { "description": "Seconds before retrying. Respect this value.", "schema": { "type": "string", "example": "60" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedResponse" }, "examples": { "Service unavailable": { "summary": "Service unavailable", "value": { "success": false, "code": "SERVICE_UNAVAILABLE", "message": "Check your request and try again.", "data": null, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":503,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":false,\"code\":\"SERVICE_UNAVAILABLE\",\"message\":\"Check your request and try again.\",\"data\":null,\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "f4G3tnay7MSvbX0sh6o+MVBLGZazDaauumzATEL7aipP+6Ub6dJgOmau+zBHXulKKDI0ogR5As94OdsVlpWcBw==" } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "licenseKey": { "type": "string", "description": "License key belonging to this app. Required for license sign-in and registration." } }, "required": [ "licenseKey" ] }, "example": { "licenseKey": "4J8N-7P2C-9K6R-3W5M" } } } }, "security": [ { "session": [] } ], "parameters": [ { "name": "X-AuthlyX-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32,128}$" }, "description": "Fresh random hexadecimal nonce. Do not reuse.", "example": "a6e4c18b379520dfa6e4c18b379520df" }, { "name": "X-AuthlyX-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Server-aligned Unix time in milliseconds.", "example": "1792843200000" }, { "name": "X-AuthlyX-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64 Ed25519 installation signature over the exact request-proof payload.", "example": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" } ], "x-fern-examples": [ { "name": "Successful", "request": { "licenseKey": "4J8N-7P2C-9K6R-3W5M" }, "headers": { "X-AuthlyX-Nonce": "a6e4c18b379520dfa6e4c18b379520df", "X-AuthlyX-Timestamp": "1792843200000", "X-AuthlyX-Signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }, "response": { "body": { "success": true, "code": "LICENSE_REDEEMED", "message": "Request completed.", "data": { "expiry": "2026-12-24T12:00:00.000Z", "plan": "Premium" }, "requestId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "verification": { "keyId": "324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e", "signedPayload": "{\"type\":\"authlyx.response.v3\",\"keyId\":\"324be2dea8bc44461b0233e51fa48902ed6b1cc671e7739af2551e0bfe68f54e\",\"httpStatus\":200,\"serverTime\":\"2026-10-24T12:00:00.000Z\",\"request\":{\"method\":\"POST\",\"path\":\"/v3/licenses/redeem\",\"nonce\":\"a6e4c18b379520dfa6e4c18b379520df\",\"bodySha256\":\"1d5fa315843a6581786f8db02426d4d6f1f34253ef21d83489d79e914f49a34f\"},\"response\":{\"success\":true,\"code\":\"LICENSE_REDEEMED\",\"message\":\"Request completed.\",\"data\":{\"expiry\":\"2026-12-24T12:00:00.000Z\",\"plan\":\"Premium\"},\"requestId\":\"98b6a22d-2ea3-4863-91f8-c575cdccf1a2\"}}", "signature": "7+fAUaV6x/KXqhQZ7wdW0oSxlRGce6JBl7ysG/ETFP7Qk57XQg8uKbZ8zAYlmQz06gR82v3VMbGp4bvHFfDdCA==" } } } } ] } } }, "tags": [ { "name": "Sign-in" }, { "name": "Sessions" }, { "name": "Offline access" }, { "name": "Cloud Variables" }, { "name": "Scripts" }, { "name": "Features" }, { "name": "Metadata" }, { "name": "Webhooks" }, { "name": "Logs" }, { "name": "Account" } ] } ``` # Complete MANAGEMENT API specification ```json { "openapi": "3.0.3", "info": { "title": "AuthlyX Management API", "version": "1.0.0-beta", "description": "Server-side management and self-hosted bot commands implemented in the rebuild. Uses account-level Elite Keys or Bot Keys, never an AppKey. Dashboard and internal staff routes are private application interfaces, not public integration APIs." }, "servers": [ { "url": "http://127.0.0.1:4000", "description": "Local development" } ], "security": [ { "managementKey": [] } ], "components": { "securitySchemes": { "managementKey": { "type": "http", "scheme": "bearer", "description": "Account-level key with the exact resource.action permission and a supporting account plan." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } }, "paths": { "/management/v1/applications": { "get": { "operationId": "list_applications", "tags": [ "Applications" ], "summary": "List applications", "description": "Requires applications.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination.", "parameters": [ { "name": "appId", "in": "query", "schema": { "type": "string" }, "description": "Application record ID; optional for listing." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nextOffset": { "type": "integer", "nullable": true } }, "required": [ "data", "nextOffset" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "response": { "body": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } ] }, "post": { "operationId": "manage_applications", "tags": [ "Applications" ], "summary": "Manage applications", "description": "Requires applications.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "edit", "delete", "pause", "resume" ], "default": "create" }, "appId": { "type": "string", "description": "Application ID. Required for app-scoped changes." }, "id": { "type": "string", "description": "Record ID. Required for actions other than create." }, "days": { "type": "integer", "minimum": 1, "maximum": 365000, "description": "Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened." }, "values": { "type": "object", "additionalProperties": true, "description": "Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions." } }, "required": [] }, "example": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "action": { "type": "string" } }, "required": [ "ok", "id", "action" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } }, "response": { "body": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } ] } }, "/management/v1/users": { "get": { "operationId": "list_users", "tags": [ "Users" ], "summary": "List users", "description": "Requires users.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination.", "parameters": [ { "name": "appId", "in": "query", "schema": { "type": "string" }, "description": "Application record ID; optional for listing." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nextOffset": { "type": "integer", "nullable": true } }, "required": [ "data", "nextOffset" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "alex", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "response": { "body": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "alex", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } ] }, "post": { "operationId": "manage_users", "tags": [ "Users" ], "summary": "Manage users", "description": "Requires users.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "edit", "delete", "ban", "unban", "pause", "resume", "extend", "shorten", "reset_sid" ], "default": "create" }, "appId": { "type": "string", "description": "Application ID. Required for app-scoped changes." }, "id": { "type": "string", "description": "Record ID. Required for actions other than create." }, "days": { "type": "integer", "minimum": 1, "maximum": 365000, "description": "Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened." }, "values": { "type": "object", "additionalProperties": true, "description": "Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions." } }, "required": [] }, "example": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "alex", "subscription": "Premium", "expiryDays": "30" } } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "action": { "type": "string" } }, "required": [ "ok", "id", "action" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "alex", "subscription": "Premium", "expiryDays": "30" } }, "response": { "body": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } ] } }, "/management/v1/licenses": { "get": { "operationId": "list_licenses", "tags": [ "Licenses" ], "summary": "List licenses", "description": "Requires licenses.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination.", "parameters": [ { "name": "appId", "in": "query", "schema": { "type": "string" }, "description": "Application record ID; optional for listing." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nextOffset": { "type": "integer", "nullable": true } }, "required": [ "data", "nextOffset" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "4J8N-7P2C-9K6R-3W5M", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "response": { "body": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "4J8N-7P2C-9K6R-3W5M", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } ] }, "post": { "operationId": "manage_licenses", "tags": [ "Licenses" ], "summary": "Manage licenses", "description": "Requires licenses.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "edit", "delete", "ban", "unban", "pause", "resume", "extend", "shorten", "reset_sid" ], "default": "create" }, "appId": { "type": "string", "description": "Application ID. Required for app-scoped changes." }, "id": { "type": "string", "description": "Record ID. Required for actions other than create." }, "days": { "type": "integer", "minimum": 1, "maximum": 365000, "description": "Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened." }, "values": { "type": "object", "additionalProperties": true, "description": "Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions." } }, "required": [] }, "example": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "4J8N-7P2C-9K6R-3W5M", "subscription": "Premium", "expiryDays": "30" } } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "action": { "type": "string" } }, "required": [ "ok", "id", "action" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "4J8N-7P2C-9K6R-3W5M", "subscription": "Premium", "expiryDays": "30" } }, "response": { "body": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } ] } }, "/management/v1/devices": { "get": { "operationId": "list_devices", "tags": [ "Devices" ], "summary": "List devices", "description": "Requires devices.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination.", "parameters": [ { "name": "appId", "in": "query", "schema": { "type": "string" }, "description": "Application record ID; optional for listing." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nextOffset": { "type": "integer", "nullable": true } }, "required": [ "data", "nextOffset" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "response": { "body": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } ] }, "post": { "operationId": "manage_devices", "tags": [ "Devices" ], "summary": "Manage devices", "description": "Requires devices.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "edit", "delete", "ban", "unban", "pause", "resume", "extend", "shorten", "reset_sid" ], "default": "create" }, "appId": { "type": "string", "description": "Application ID. Required for app-scoped changes." }, "id": { "type": "string", "description": "Record ID. Required for actions other than create." }, "days": { "type": "integer", "minimum": 1, "maximum": 365000, "description": "Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened." }, "values": { "type": "object", "additionalProperties": true, "description": "Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions." } }, "required": [] }, "example": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "action": { "type": "string" } }, "required": [ "ok", "id", "action" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } }, "response": { "body": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } ] } }, "/management/v1/subscriptions": { "get": { "operationId": "list_subscriptions", "tags": [ "Plans" ], "summary": "List plans", "description": "Requires subscriptions.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination.", "parameters": [ { "name": "appId", "in": "query", "schema": { "type": "string" }, "description": "Application record ID; optional for listing." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nextOffset": { "type": "integer", "nullable": true } }, "required": [ "data", "nextOffset" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "response": { "body": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } ] }, "post": { "operationId": "manage_subscriptions", "tags": [ "Plans" ], "summary": "Manage plans", "description": "Requires subscriptions.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "edit", "delete" ], "default": "create" }, "appId": { "type": "string", "description": "Application ID. Required for app-scoped changes." }, "id": { "type": "string", "description": "Record ID. Required for actions other than create." }, "days": { "type": "integer", "minimum": 1, "maximum": 365000, "description": "Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened." }, "values": { "type": "object", "additionalProperties": true, "description": "Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions." } }, "required": [] }, "example": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "action": { "type": "string" } }, "required": [ "ok", "id", "action" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } }, "response": { "body": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } ] } }, "/management/v1/variables": { "get": { "operationId": "list_variables", "tags": [ "Cloud variables" ], "summary": "List cloud variables", "description": "Requires variables.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination.", "parameters": [ { "name": "appId", "in": "query", "schema": { "type": "string" }, "description": "Application record ID; optional for listing." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "nextOffset": { "type": "integer", "nullable": true } }, "required": [ "data", "nextOffset" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "response": { "body": { "data": [ { "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "name": "Premium", "status": "Active", "created": "2026-10-24" } ], "nextOffset": null } } } ] }, "post": { "operationId": "manage_variables", "tags": [ "Cloud variables" ], "summary": "Manage cloud variables", "description": "Requires variables.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "edit", "delete", "pause", "resume" ], "default": "create" }, "appId": { "type": "string", "description": "Application ID. Required for app-scoped changes." }, "id": { "type": "string", "description": "Record ID. Required for actions other than create." }, "days": { "type": "integer", "minimum": 1, "maximum": 365000, "description": "Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened." }, "values": { "type": "object", "additionalProperties": true, "description": "Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions." } }, "required": [] }, "example": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "action": { "type": "string" } }, "required": [ "ok", "id", "action" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "action": "create", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c", "values": { "name": "Premium", "subscription": "Premium", "expiryDays": "30" } }, "response": { "body": { "ok": true, "id": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "action": "create" } } } ] } }, "/bots/v1/commands": { "post": { "operationId": "bot_command", "tags": [ "Bots" ], "summary": "Run a bot command", "description": "Requires a Bot Key with the corresponding management scope. Elite Keys are rejected here. apps lists up to 30 apps; status shows one app; license creates a Default-plan key; pause/resume control an app; ban/unban control a user, license or device.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "enum": [ "apps", "status", "license", "pause", "resume", "ban", "unban" ] }, "appId": { "type": "string", "description": "Application ID, required except for apps." }, "resource": { "type": "string", "enum": [ "users", "licenses", "devices" ], "description": "Required for ban and unban." }, "id": { "type": "string", "description": "Identity record ID for ban/unban." }, "days": { "type": "string", "default": "30", "description": "License duration when command is license." } }, "required": [ "command" ] }, "example": { "command": "status", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c" } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "id": { "type": "string" } }, "required": [ "text" ] }, "examples": { "Successful": { "summary": "Successful", "value": { "text": "MyApp is active." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Bad request": { "summary": "Bad request", "value": { "error": "Bad request. Check the request and your key permissions." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "error": "Unauthorized. Check the request and your key permissions." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Forbidden": { "summary": "Forbidden", "value": { "error": "Forbidden. Check the request and your key permissions." } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Not found": { "summary": "Not found", "value": { "error": "Not found. Check the request and your key permissions." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "Too many requests": { "summary": "Too many requests", "value": { "error": "Too many requests. Check the request and your key permissions." } } } } } } }, "x-fern-examples": [ { "name": "Successful", "request": { "command": "status", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c" }, "response": { "body": { "text": "MyApp is active." } } } ] } } } } ``` # Endpoint README: POST /api/v1/init # POST /api/v1/init Init Archived request fields from the V1 init handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `owner_id` | No / conditional | string | Legacy developer owner ID. | | `app_name` | No / conditional | string | Legacy application name. | | `version` | No / conditional | string | Version string reported by your application. | | `secret` | No / conditional | string | Legacy application secret; never put it in a URL. | | `hash` | No / conditional | string | Build hash used for the app hash policy. | | `ip` | No / conditional | string | IP field used by the legacy operation. Follow that version's documented behavior. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/init' \ -H 'Content-Type: application/json' \ --data-raw '{ "owner_id": "459010927960", "app_name": "MyApp", "version": "1.0.0", "secret": "b7f8c2e46a9130d5b7f8c2e46a9130d5b7f8c2e46a9130d5b7f8c2e46a9130d5", "hash": "a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f", "ip": "197.210.54.18" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/login # POST /api/v1/login Login Archived request fields from the V1 login handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `username` | No / conditional | string | App username. | | `password` | No / conditional | string | App password. | | `sid` | No / conditional | string | System identifier; legacy routes can accept this as an identifier alias. | | `hwid` | No / conditional | string | Legacy device/system identifier. | | `ip` | No / conditional | string | IP field used by the legacy operation. Follow that version's documented behavior. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/login' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "username": "alex", "password": "River-Glass-29", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/register # POST /api/v1/register Register Archived request fields from the V1 register handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `username` | No / conditional | string | App username. | | `password` | No / conditional | string | App password. | | `email` | No / conditional | string | App-user email when required by this operation. | | `key` | No / conditional | string | Key required by this operation. | | `sid` | No / conditional | string | System identifier; legacy routes can accept this as an identifier alias. | | `hwid` | No / conditional | string | Legacy device/system identifier. | | `ip` | No / conditional | string | IP field used by the legacy operation. Follow that version's documented behavior. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/register' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "username": "alex", "password": "River-Glass-29", "email": "alex@example.com", "key": "preferredLanguage", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/licenses # POST /api/v1/licenses Licenses Archived request fields from the V1 licenses handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `license_key` | No / conditional | string | License key belonging to this application. | | `sid` | No / conditional | string | System identifier; legacy routes can accept this as an identifier alias. | | `hwid` | No / conditional | string | Legacy device/system identifier. | | `ip` | No / conditional | string | IP field used by the legacy operation. Follow that version's documented behavior. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/licenses' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "license_key": "MyApp", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/licenses/verify # POST /api/v1/licenses/verify Licenses verify Archived request fields from the V1 verifyLicense handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `license_key` | No / conditional | string | License key belonging to this application. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/licenses/verify' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "license_key": "MyApp" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/extend # POST /api/v1/extend Extend Archived request fields from the V1 extend handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `username` | No / conditional | string | App username. | | `license_key` | No / conditional | string | License key belonging to this application. | | `sid` | No / conditional | string | System identifier; legacy routes can accept this as an identifier alias. | | `hwid` | No / conditional | string | Legacy device/system identifier. | | `ip` | No / conditional | string | IP field used by the legacy operation. Follow that version's documented behavior. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/extend' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "username": "alex", "license_key": "MyApp", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/variables # POST /api/v1/variables Variables Archived request fields from the V1 variables handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `var_key` | No / conditional | string | Cloud variable name. | | `var_value` | No / conditional | string | Cloud variable value. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/variables' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "var_key": "MyApp", "var_value": "MyApp" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/variables/set # POST /api/v1/variables/set Variables set Archived request fields from the V1 variables handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `var_key` | No / conditional | string | Cloud variable name. | | `var_value` | No / conditional | string | Cloud variable value. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/variables/set' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "var_key": "MyApp", "var_value": "MyApp" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/logs # POST /api/v1/logs Logs Archived request fields from the V1 logs handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `message` | No / conditional | string | Message text. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/logs' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "message": "License verified. Application started." }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/validate-session # POST /api/v1/validate-session Validate session Archived request fields from the V1 validateSession handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/validate-session' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/chats/send # POST /api/v1/chats/send Chats send Archived request fields from the V1 chats handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `channel_name` | No / conditional | string | Chat channel name. | | `message` | No / conditional | string | Message text. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/chats/send' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "channel_name": "MyApp", "message": "License verified. Application started." }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/chats/get # POST /api/v1/chats/get Chats get Archived request fields from the V1 chats handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `channel_name` | No / conditional | string | Chat channel name. | | `message` | No / conditional | string | Message text. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/chats/get' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "channel_name": "MyApp", "message": "License verified. Application started." }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/device-auth # POST /api/v1/device-auth Device auth Archived request fields from the V1 device-auth handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `device_type` | No / conditional | string | Device type used by the legacy operation. | | `device_id` | No / conditional | string | Device identifier used by the legacy operation. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/device-auth' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "device_type": "MyApp", "device_id": "MyApp" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v1/change-password # POST /api/v1/change-password Change password Archived request fields from the V1 change-password handler. Consult your matching V1 SDK for field requirements and historical response handling. ## Request format - Version/group: **v1** (end of support) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | No / conditional | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `old_password` | No / conditional | string | Current app-user password. | | `new_password` | No / conditional | string | Replacement app-user password. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v1/change-password' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "old_password": "MyApp", "new_password": "MyApp" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | V1 response. Check success and code; HTTP success alone is not authorization. | | 400 | Invalid request. | | 401 | Invalid session or credentials. | | 403 | Access denied. | | 429 | Rate limit reached. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/init # POST /api/v2/init Initialize a session The first call every client must make. Verifies owner credentials, runs IP/VPN/country checks, validates the optional executable hash, checks the app version, and returns a `session_id` valid for 24 hours. All other v2 endpoints require this session_id. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `owner_id` | Yes | string | Developer ID from the AuthlyX dashboard. | | `app_name` | Yes | string | Exact registered app name (case-sensitive). | | `secret` | Yes | string | App secret key. Never expose client-side. | | `version` | Yes | string | Client version string used for version control enforcement. | | `hash` | No / conditional | string | SHA-256 hash of the compiled executable. Required only if hash checking is enabled. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/init' \ -H 'Content-Type: application/json' \ --data-raw '{ "owner_id": "12345678", "app_name": "MyApp", "secret": "your-secret-key", "version": "1.3", "hash": "a3f5c9..." }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Session created successfully. | | 400 | Missing or invalid fields. | | 401 | Invalid owner or secret. | | 403 | Access blocked by IP, VPN, country, or app status. | | 426 | Version mismatch or update required. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/validate-session # POST /api/v2/validate-session Validate a session Checks whether a session is still active and not expired. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Active session ID from a successful Init call. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/validate-session' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Session is valid. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/login # POST /api/v2/login Authenticate a user Authenticates a user with username and password against an active session. Enforces device limits, IP rules, and account status checks. Returns a refreshed session_id and full user details on success. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `username` | Yes | string | App username. | | `password` | Yes | string | App password. | | `sid` | Yes | string | System/HWID identifier. Enforces device limits and locks the session to this machine. | | `ip` | No / conditional | string | Client IP address. Inferred from request headers if omitted. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/login' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "username": "xela", "password": "hunter2", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Login successful. | | 400 | Missing or invalid fields. | | 401 | Session or credential check failed. | | 403 | Access blocked by security policy or account status. | | 404 | User not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/licenses # POST /api/v2/licenses Authenticate a license key Authenticates a license key against an active session. Use this when your app distributes license keys rather than user accounts. Enforces device limits and, on success, registers the device and updates the session and license's `sid`/`ip_address`/`last_login`. For a read-only status check that does not touch device or session state, use `POST /api/v2/licenses/verify` instead. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `license_key` | Yes | string | The license key to authenticate. | | `sid` | Yes | string | Unique system identifier (or hwid). Enforces device limits and locks the session to this machine. | | `ip` | No / conditional | string | Client IP address. Inferred from request headers if omitted. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/licenses' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Login successful. Returns license details and a refreshed session. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 403 | Access blocked by license status or device policy. | | 404 | License key not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/licenses/verify # POST /api/v2/licenses/verify Verify a license's status Read-only license status check: exists, not banned, not paused, not expired. Unlike `POST /api/v2/licenses`, this does not register a device, does not enforce `max_devices`, and does not update `sid`/`ip_address`/`last_login` on the license or the session. Intended for periodic background re-checks of an already-activated license. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `license_key` | Yes | string | The license key to check. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/licenses/verify' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | License is valid. Returns license details; no device, session, or usage state is modified. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 403 | License is blocked. | | 404 | License key not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/register # POST /api/v2/register Register a new user Creates a new user account by redeeming an unused license key. Returns a new session_id and user details on success. The license key is consumed on successful registration. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `username` | Yes | string | App username. | | `password` | Yes | string | App password. | | `key` | Yes | string | Unused license key. Consumed on successful registration. | | `email` | No / conditional | string | App-user email when required by this operation. | | `sid` | No / conditional | string | System identifier to bind the device on registration. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/register' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "username": "xela", "password": "hunter2", "key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX", "email": "user@example.com", "sid": "S-1-5-21-...." }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 201 | Account created successfully. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 403 | License blocked or not eligible. | | 404 | License key not found. | | 409 | Username already taken. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/extend # POST /api/v2/extend Extend a user's subscription Extends a user's subscription by redeeming an unused license key. The key's duration is added on top of the current expiry date. If the user is already expired, the extension starts from today. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `username` | Yes | string | App username. | | `license_key` | Yes | string | Unused license key whose duration will be applied. | | `sid` | Yes | string | System identifier for security consistency check. | | `ip` | No / conditional | string | IP field used by the legacy operation. Follow that version's documented behavior. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/extend' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "username": "xela", "license_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX", "sid": "S-1-5-21-....", "ip": "102.88.xxx.xxx" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Extension successful. | | 400 | Missing fields or invalid duration. | | 401 | Session invalid or expired. | | 403 | User or license blocked. | | 404 | User or license not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/change-password # POST /api/v2/change-password Change user password Changes the password of the user linked to the active session. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `old_password` | Yes | string | Current app-user password. | | `new_password` | Yes | string | Replacement app-user password. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/change-password' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "old_password": "old", "new_password": "new" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Password changed successfully. | | 400 | Missing fields or password reused. | | 401 | Session or password check failed. | | 403 | Password change disabled or user blocked. | | 404 | User not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/device-auth # POST /api/v2/device-auth Authenticate a device Authenticates a hardware device (motherboard or processor) against the active session. Returns device subscription details on success. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `device_type` | Yes | string | Device type used by the legacy operation. Allowed: "motherboard", "processor" | | `device_id` | Yes | string | Unique hardware identifier string extracted from the client machine. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/device-auth' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "device_type": "motherboard", "device_id": "PDPCF001X4YJ2Q" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Device authenticated. | | 400 | Missing fields or invalid device type. | | 401 | Session invalid or expired. | | 403 | Device banned, paused, or expired. | | 404 | Device not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/variables # POST /api/v2/variables Get a cloud variable Retrieves the value of a cloud variable for the current app. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `var_key` | Yes | string | Key identifier of the cloud variable to retrieve. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/variables' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "var_key": "my_variable" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Variable retrieved. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 404 | Variable not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/variables/set # POST /api/v2/variables/set Set a cloud variable Creates or updates a cloud variable for the current app. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `var_key` | Yes | string | Cloud variable name. | | `var_value` | Yes | string | String value to write to the variable. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/variables/set' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "var_key": "my_variable", "var_value": "hello" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Variable updated. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 404 | Variable key not found in app settings. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/logs # POST /api/v2/logs Send a log message Sends a log message from the client to be stored or forwarded to a configured webhook. If app logging is disabled, the endpoint still returns 200 but does nothing. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `message` | Yes | string | Log text or data payload from the client. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/logs' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "message": "Hello from the client" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Log stored. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 403 | Log quota exceeded. | | 500 | Internal error or webhook delivery failed. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/chats/send # POST /api/v2/chats/send Send a chat message Broadcasts a message to the specified app chat channel. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `channel_name` | Yes | string | Chat channel name. | | `message` | Yes | string | Message text. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/chats/send' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "channel_name": "general", "message": "hello" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Message sent. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 403 | User muted or not linked. | | 404 | Channel not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/chats/get # POST /api/v2/chats/get Get chat messages Retrieves messages from the specified app chat channel with pagination support. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `channel_name` | Yes | string | Chat channel name. | | `limit` | No / conditional | integer | Maximum number of messages to return. Default: 50 | | `cursor` | No / conditional | string,null | Pagination cursor for older messages. Pass null for the first request. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/chats/get' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "dc1cea3a75", "channel_name": "general", "limit": 50, "cursor": null }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Messages retrieved. | | 400 | Missing or invalid fields. | | 401 | Session invalid or expired. | | 403 | Access denied. | | 404 | Channel not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: GET /api/elite-key # GET /api/elite-key Execute an Elite Key action (GET) Server-side management API. Requires the Elite plan. Pass `function` + `action` to route the request to the correct module. All parameters can also be sent as a form-urlencoded POST body. **Modules:** `license`, `user`, `device`, `variable`, `subscription`, `version`, `response`, `app`. **Security:** Never use from client code. Restrict usage with IP/domain whitelists in Elite Key Settings. Reset immediately if the key leaks. ## Request format - Version/group: **v2** (legacy) - Input location: **URL query parameters**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send no request body. JSON response content does not mean a GET request needs a JSON body. ## Authentication and headers The legacy `key` field is the Elite management credential. Keep this integration server-side. The GET variant exposes it in a URL; prefer the supported form POST alternative when maintaining this old integration. ## URL parameters | Parameter | Required | Type | Meaning | | --- | --- | --- | --- | | `key` | Yes | string | Your Elite Key from the dashboard. | | `function` | Yes | string | Allowed: "license", "user", "device", "variable", "subscription", "version", "response", "app" | | `action` | Yes | string | Operation to run. Available actions per function: - `license`: generate, edit, delete, extend, shorten, ban, unban, pause, unpause - `user`: generate, edit, delete, extend, shorten, ban, unban, pause, unpause, reset_password, verify_password - `device`: create, edit, delete, extend, ban, pause - `variable`: set, delete - `subscription`: create, edit, delete - `version`: add, edit, remove - `response`: set, reset - `app`: edit | | `url_prefix` | Yes | string | Your app's URL prefix. | | `app_name` | Yes | string | Registered app name. | URL-encode values. New integrations must keep credentials in Authorization headers; the legacy Elite Key GET route above is a compatibility exception. ## Body fields None. This handler does not use a GET JSON body for filters. ## Request example Replace placeholder values before sending. ```bash curl -X GET 'https://authly.cc/api/elite-key?key=YOUR_ELITE_KEY&function=license&action=info&url_prefix=YOUR_APP_URL_PREFIX&app_name=YOUR_APP_NAME' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Action completed. | | 400 | Missing or invalid parameters. | | 401 | Elite Key invalid or inactive. | | 403 | Plan requirement, disabled action, or IP/domain restriction. | | 404 | App, license, user, or subscription not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/elite-key # POST /api/elite-key Execute an Elite Key action (POST) Server-side management API. Requires the Elite plan. Pass `function` + `action` to route the request to the correct module. All parameters can also be sent as a form-urlencoded POST body. **Modules:** `license`, `user`, `device`, `variable`, `subscription`, `version`, `response`, `app`. **Security:** Never use from client code. Restrict usage with IP/domain whitelists in Elite Key Settings. Reset immediately if the key leaks. ## Request format - Version/group: **v2** (legacy) - Input location: **Form body (legacy)**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/x-www-form-urlencoded`. This legacy route documents a form-encoded body. JSON is not a documented substitute. ## Authentication and headers The legacy `key` field is the Elite management credential. Keep this integration server-side. The GET variant exposes it in a URL; prefer the supported form POST alternative when maintaining this old integration. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `key` | Yes | string | Legacy Elite management credential. | | `function` | Yes | string | Legacy Elite Key module name. Allowed: "license", "user", "device", "variable", "subscription", "version", "response", "app" | | `action` | Yes | string | Action to perform in that module. | | `url_prefix` | Yes | string | URL-prefix value expected by the legacy Elite Key application selection. | | `app_name` | Yes | string | Legacy application name. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/elite-key' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'key=preferredLanguage' \ --data-urlencode 'function=license' \ --data-urlencode 'action=create' \ --data-urlencode 'url_prefix=MyApp' \ --data-urlencode 'app_name=MyApp' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Action completed. | | 400 | Missing or invalid parameters. | | 401 | Elite Key invalid. | | 403 | Plan, permission, or access denied. | | 404 | Resource not found. | | 500 | Unexpected server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /api/v2/blacklist/check # POST /api/v2/blacklist/check Check blacklist Legacy V2 check for a system ID or IP blacklist entry in the session application. The handler uses hwid first, then sid. If ip is omitted, it reads the connection/forwarded address. Uses V2 middleware and its deployed replay/signature configuration, not V3 request proof. ## Request format - Version/group: **v2** (legacy) - Input location: **JSON body**. - Base URL: `https://authly.cc`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the legacy fields below, including `session_id` after initialization when required. V2 middleware and its deployed signing/replay settings still apply; V3 proof headers do not replace them. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `session_id` | Yes | string | Session ID from this version of the legacy API, not a V3 bearer token. | | `hwid` | No / conditional | string | Legacy device/system identifier. | | `sid` | No / conditional | string | System identifier; legacy routes can accept this as an identifier alias. | | `ip` | No / conditional | string | IP field used by the legacy operation. Follow that version's documented behavior. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'https://authly.cc/api/v2/blacklist/check' \ -H 'Content-Type: application/json' \ --data-raw '{ "session_id": "c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140c7be084b6eaf9140", "hwid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "ip": "197.210.54.18" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Blacklist result. | | 400 | Missing session_id. | | 401 | Invalid or expired session. | | 429 | Rate limit reached. | | 500 | Internal server error. | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/initialize # POST /v3/initialize Initialize Checks your AppKey and app version. Sign in to receive the update for your assigned release channel. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers The AppKey identifies the application. Login additionally requires the credentials and installation challenge proof documented by its request type. Initialization alone does not sign an identity in. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | No | Random nonce for binding and verifying the signed response. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `appKey` | Yes | string | Application identifier copied from the dashboard. Not an Elite Key or Bot Key. Pattern: ^[a-z0-9][a-z0-9_-]{0,31}_[a-f0-9]{48}$ | | `version` | Yes | string | Version of the application making this request, for example 1.0.0. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/v3/initialize' \ -H 'Content-Type: application/json' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ --data-raw '{ "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/challenge # POST /v3/challenge Prepare sign-in Creates a single-use login challenge for an Ed25519 installation public key. Challenges expire after two minutes. Sign the exact challenge payload together with the normalized login operation; the SDK handles this. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers The AppKey identifies the application. Login additionally requires the credentials and installation challenge proof documented by its request type. Initialization alone does not sign an identity in. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | No | Random nonce for binding and verifying the signed response. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `appKey` | Yes | string | Application identifier copied from the dashboard. Not an Elite Key or Bot Key. | | `installationPublicKey` | Yes | string | PEM-encoded Ed25519 public key for this installation. Never send its private key. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/v3/challenge' \ -H 'Content-Type: application/json' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ --data-raw '{ "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "installationPublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/login # POST /v3/login Login Sign in with a license key, username and password, or an approved device. AuthlyX checks access and returns a session. Prepare sign-in first to get the required challenge proof. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers The AppKey identifies the application. Login additionally requires the credentials and installation challenge proof documented by its request type. Initialization alone does not sign an identity in. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | No | Random nonce for binding and verifying the signed response. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `appKey` | Yes | string | Application identifier copied from the dashboard. Not an Elite Key or Bot Key. | | `version` | Yes | string | Version of the application making this request, for example 1.0.0. | | `sid` | Yes | string | Stable platform system identifier. Windows SDK defaults use the Windows user SID. | | `hash` | No / conditional | string | SHA-256 build hash. Required by policy when hash checking is enabled. | | `username` | No / conditional | string | App username, required for user and register sign-in. Between 1 and 200 characters. | | `password` | No / conditional | string | App password, required for user and register sign-in. Between 1 and 256 characters. | | `licenseKey` | No / conditional | string | License key belonging to this app. Required for license sign-in and registration. | | `installationPublicKey` | No / conditional | string | PEM-encoded Ed25519 public key for this installation. Never send its private key. | | `challengeId` | Yes | string | ID from an unexpired single-use challenge for this operation. | | `signature` | Yes | string | Base64 Ed25519 signature over the challenge proof payload. | | `type` | Yes | string | Sign-in method: user, license, device or register. Allowed: "license", "user", "device" | | `email` | No / conditional | string | Optional app-user email for registration. Format: email | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/v3/login' \ -H 'Content-Type: application/json' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ --data-raw '{ "type": "license", "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0", "licenseKey": "YOUR_LICENSE_KEY", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/register # POST /v3/register Register Creates an app user with a username, password and unused license. Prepare sign-in first and sign the register operation. This is not AuthlyX dashboard registration. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers The AppKey identifies the application. Login additionally requires the credentials and installation challenge proof documented by its request type. Initialization alone does not sign an identity in. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | No | Random nonce for binding and verifying the signed response. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `appKey` | Yes | string | Application identifier copied from the dashboard. Not an Elite Key or Bot Key. | | `version` | Yes | string | Version of the application making this request, for example 1.0.0. | | `sid` | Yes | string | Stable platform system identifier. Windows SDK defaults use the Windows user SID. | | `hash` | No / conditional | string | SHA-256 build hash. Required by policy when hash checking is enabled. | | `username` | No / conditional | string | App username, required for user and register sign-in. Between 1 and 200 characters. | | `password` | No / conditional | string | App password, required for user and register sign-in. Between 1 and 256 characters. | | `licenseKey` | No / conditional | string | License key belonging to this app. Required for license sign-in and registration. | | `installationPublicKey` | No / conditional | string | PEM-encoded Ed25519 public key for this installation. Never send its private key. | | `challengeId` | Yes | string | ID from an unexpired single-use challenge for this operation. | | `signature` | Yes | string | Base64 Ed25519 signature over the challenge proof payload. | | `type` | Yes | string | Allowed: "register" Default: "register" | | `email` | No / conditional | string | Optional app-user email for registration. Format: email | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/v3/register' \ -H 'Content-Type: application/json' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ --data-raw '{ "appKey": "ger_5607ad6df93c49359adfa5a8dc6f3c96cacd6275d9a44d78", "version": "1.0.0", "sid": "S-1-5-21-3349523261-4242746980-1390621393-1001", "hash": "a75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109fa75c96e38b2d109f", "username": "alex", "password": "River-Glass-29", "licenseKey": "4J8N-7P2C-9K6R-3W5M", "installationPublicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA6kpsY+KcUgq+9VB7Ey7F+ZVHdq6+vnuSQh7qaRRG0iw=\n-----END PUBLIC KEY-----\n", "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==", "type": "register", "email": "alex@example.com" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/session/check # POST /v3/session/check Check session Checks the signed-in identity and its current access policies, then renews the server-issued access deadline. The session stays bound to its original identity, app, system ID and installation key. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields Send the empty object `{}`. Authorization and request proof still come from the headers when required. ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/session/check' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{}' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/session/logout # POST /v3/session/logout Sign out Revokes the current server session. Clear local authorization and stop heartbeat work. This endpoint does not terminate the developer application. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields Send the empty object `{}`. Authorization and request proof still come from the headers when required. ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/session/logout' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{}' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/offline/challenge # POST /v3/offline/challenge Prepare offline access Requires a valid V3 session and an enabled app offline window. Creates a challenge tied to that session and installation. It does not grant an offline permit by itself. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields Send the empty object `{}`. Authorization and request proof still come from the headers when required. ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/offline/challenge' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{}' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/offline/permit # POST /v3/offline/permit Get offline permit Exchanges the offline challenge proof for a signed, installation-bound permit. Its deadline cannot exceed the app window or identity entitlement. Offline access cannot immediately learn about later bans. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `challengeId` | Yes | string | ID from an unexpired single-use challenge for this operation. | | `signature` | Yes | string | Base64 Ed25519 signature over the challenge proof payload. | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/offline/permit' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "challengeId": "98b6a22d-2ea3-4863-91f8-c575cdccf1a2", "signature": "DQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ==" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/data/get # POST /v3/data/get Read a variable Reads an active cloud variable by name from the signed-in application. A paused or missing variable is rejected. Values become current when the app next fetches them; there is no unsolicited push. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `name` | Yes | string | Cloud variable name. | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/data/get' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "name": "download_url" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/data/set # POST /v3/data/set Update a variable Updates an existing cloud variable only when Allow remote updates is enabled. Paused variables cannot be changed. The authenticated app determines the scope. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `name` | Yes | string | | | `value` | Yes | string | Maximum length: 8192 | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/data/set' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "name": "download_url", "value": "en" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/scripts/get # POST /v3/scripts/get Fetch a script Fetches the named script release, optionally at a specific revision. The SDK verifies script signatures. Fetching a script does not execute it. Distributed scripts are readable by authorized clients and must not contain server secrets. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `name` | Yes | string | Published script name. | | `revision` | No / conditional | integer | Optional positive revision number. Omit to request the current published revision. Minimum: 1 | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/scripts/get' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "name": "startup", "revision": 3 }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/features/list # POST /v3/features/list Get all features Returns the effective feature values for this identity. Requires Plus or Elite. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields Send the empty object `{}`. Authorization and request proof still come from the headers when required. ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/features/list' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{}' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/features/get # POST /v3/features/get Get feature value Reads one effective value for the signed-in identity. Features require Plus or Elite; metadata requires Elite. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `name` | Yes | string | | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/features/get' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "name": "videoQuality" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/features/check # POST /v3/features/check Check feature Returns enabled=true only for an enabled Bool feature whose effective value is true. Missing, disabled or non-Bool features return enabled=false. Requires Plus or Elite. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `name` | Yes | string | Feature name defined by the developer. | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/features/check' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "name": "exportPdf" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/metadata/list # POST /v3/metadata/list Get all metadata Returns app-readable metadata for this identity. Private fields are excluded. Requires Elite. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields Send the empty object `{}`. Authorization and request proof still come from the headers when required. ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/metadata/list' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{}' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/metadata/get # POST /v3/metadata/get Get metadata value Reads one effective value for the signed-in identity. Features require Plus or Elite; metadata requires Elite. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `key` | Yes | string | Key required by this operation. | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/metadata/get' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "key": "preferredLanguage" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/metadata/set # POST /v3/metadata/set Update metadata Updates an existing SDK-visible field that the developer explicitly marked writable on this identity. Requires Elite. Cannot create fields, write private fields or change inherited plan defaults. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `key` | Yes | string | Existing metadata field name marked writable by the developer. | | `value` | Yes | string / number / boolean / string | New scalar value. Allowed types are string, number, boolean and null. | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/metadata/set' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "key": "preferredLanguage", "value": "en" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/metadata/check # POST /v3/metadata/check Check metadata Returns enabled=true only when the app-readable field exists and its value is Bool true. Requires Elite. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `key` | Yes | string | Key required by this operation. | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/metadata/check' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "key": "emailVerified" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/webhooks/send # POST /v3/webhooks/send Send webhook Send text or JSON data to the webhooks enabled for this event in your dashboard. The webhook URL stays on AuthlyX. Requires Plus or Elite. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `event` | Yes | string | Pattern: ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$ | | `message` | No / conditional | string | Message text. Maximum length: 2000 | | `data` | No / conditional | object | | | `idempotencyKey` | No / conditional | string | Maximum length: 100 | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/webhooks/send' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "event": "report.exported", "message": "Alex exported the monthly report.", "data": { "reportId": "REPORT-1042", "format": "pdf" }, "idempotencyKey": "export-1042" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/logs/add # POST /v3/logs/add Send log Adds a developer-defined message to the signed-in application App logs. Plan limits apply. Do not include credentials or private customer content. These are separate from dashboard audit events. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `message` | Yes | string | Message text. Minimum length: 1 Maximum length: 2000 | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/logs/add' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "message": "License verified. Application started." }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/account/password # POST /v3/account/password Change password Changes the signed-in app user password after checking the current password. License-only and device-only sessions cannot change an app account password. This does not change the developer dashboard password. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `currentPassword` | Yes | string | Current password of the signed-in app user. | | `newPassword` | Yes | string | Replacement app password, between 1 and 256 characters. Minimum length: 1 Maximum length: 256 | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/account/password' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "currentPassword": "River-Glass-29", "newPassword": "Maple-River-42" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /v3/licenses/redeem # POST /v3/licenses/redeem Redeem license Redeems an eligible unused license from the same application for the signed-in app user. The server applies plan and expiry rules and links the license. A device or license-only session cannot redeem on behalf of another user. ## Request format - Version/group: **v3** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use the signed-in V3 session token in `Authorization: Bearer SESSION_TOKEN`. Installation proof is also required; a bearer token alone is insufficient. | Header | Required | Meaning | | --- | --- | --- | | `X-AuthlyX-Nonce` | Yes | Fresh random hexadecimal nonce. Do not reuse. Pattern: ^[a-f0-9]{32,128}$ | | `X-AuthlyX-Timestamp` | Yes | Server-aligned Unix time in milliseconds. | | `X-AuthlyX-Signature` | Yes | Base64 Ed25519 installation signature over the exact request-proof payload. | ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `licenseKey` | Yes | string | License key belonging to this app. Required for license sign-in and registration. | ## Request example Replace placeholder values before sending. Generate fresh V3 request-proof headers for these exact bytes. ```bash curl -X POST 'http://127.0.0.1:4000/v3/licenses/redeem' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_SESSION_TOKEN' \ -H 'X-AuthlyX-Nonce: GENERATED_FRESH_HEX_NONCE' \ -H 'X-AuthlyX-Timestamp: SERVER_ALIGNED_UNIX_MILLISECONDS' \ -H 'X-AuthlyX-Signature: GENERATED_SIGNATURE' \ --data-raw '{ "licenseKey": "4J8N-7P2C-9K6R-3W5M" }' ``` The SDK handles nonce generation, proof construction and signed-response verification. Do not paste the placeholder signature or hash pretty-printed bytes and then send a different body. V3 accepts at most 16 KB of JSON request data. ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 413 | Payload too large | | 415 | Unsupported content type | | 429 | Too many requests | | 503 | Service unavailable | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Verify the server signature before trusting authorization data. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: GET /management/v1/applications # GET /management/v1/applications List applications Requires applications.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination. ## Request format - Version/group: **management** (rebuild beta) - Input location: **URL query parameters**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send no request body. JSON response content does not mean a GET request needs a JSON body. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters | Parameter | Required | Type | Meaning | | --- | --- | --- | --- | | `appId` | No | string | Application record ID; optional for listing. | | `limit` | No | integer | Default: 1000 Minimum: 1 Maximum: 1000 | | `offset` | No | integer | Default: 0 Minimum: 0 Maximum: 100000 | URL-encode values. New integrations must keep credentials in Authorization headers; the legacy Elite Key GET route above is a compatibility exception. ## Body fields None. This handler does not use a GET JSON body for filters. ## Request example Replace placeholder values before sending. ```bash curl -X GET 'http://127.0.0.1:4000/management/v1/applications?appId=YOUR_APP_ID&limit=1000&offset=0' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /management/v1/applications # POST /management/v1/applications Manage applications Requires applications.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code. ## Request format - Version/group: **management** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `action` | No / conditional | string | Action to perform in that module. Allowed: "create", "edit", "delete", "pause", "resume" Default: "create" | | `appId` | No / conditional | string | Application ID. Required for app-scoped changes. | | `id` | No / conditional | string | Record ID. Required for actions other than create. | | `days` | No / conditional | integer | Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened. Minimum: 1 Maximum: 365000 | | `values` | No / conditional | object | Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/management/v1/applications' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \ --data-raw '{ "action": "create", "values": { "name": "My App" } }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: GET /management/v1/users # GET /management/v1/users List users Requires users.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination. ## Request format - Version/group: **management** (rebuild beta) - Input location: **URL query parameters**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send no request body. JSON response content does not mean a GET request needs a JSON body. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters | Parameter | Required | Type | Meaning | | --- | --- | --- | --- | | `appId` | No | string | Application record ID; optional for listing. | | `limit` | No | integer | Default: 1000 Minimum: 1 Maximum: 1000 | | `offset` | No | integer | Default: 0 Minimum: 0 Maximum: 100000 | URL-encode values. New integrations must keep credentials in Authorization headers; the legacy Elite Key GET route above is a compatibility exception. ## Body fields None. This handler does not use a GET JSON body for filters. ## Request example Replace placeholder values before sending. ```bash curl -X GET 'http://127.0.0.1:4000/management/v1/users?appId=YOUR_APP_ID&limit=1000&offset=0' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /management/v1/users # POST /management/v1/users Manage users Requires users.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code. ## Request format - Version/group: **management** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `action` | No / conditional | string | Action to perform in that module. Allowed: "create", "edit", "delete", "ban", "unban", "pause", "resume", "extend", "shorten", "reset_sid" Default: "create" | | `appId` | No / conditional | string | Application ID. Required for app-scoped changes. | | `id` | No / conditional | string | Record ID. Required for actions other than create. | | `days` | No / conditional | integer | Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened. Minimum: 1 Maximum: 365000 | | `values` | No / conditional | object | Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/management/v1/users' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \ --data-raw '{ "action": "create", "appId": "YOUR_APP_ID", "values": { "name": "YOUR_RECORD_NAME" } }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: GET /management/v1/licenses # GET /management/v1/licenses List licenses Requires licenses.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination. ## Request format - Version/group: **management** (rebuild beta) - Input location: **URL query parameters**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send no request body. JSON response content does not mean a GET request needs a JSON body. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters | Parameter | Required | Type | Meaning | | --- | --- | --- | --- | | `appId` | No | string | Application record ID; optional for listing. | | `limit` | No | integer | Default: 1000 Minimum: 1 Maximum: 1000 | | `offset` | No | integer | Default: 0 Minimum: 0 Maximum: 100000 | URL-encode values. New integrations must keep credentials in Authorization headers; the legacy Elite Key GET route above is a compatibility exception. ## Body fields None. This handler does not use a GET JSON body for filters. ## Request example Replace placeholder values before sending. ```bash curl -X GET 'http://127.0.0.1:4000/management/v1/licenses?appId=YOUR_APP_ID&limit=1000&offset=0' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /management/v1/licenses # POST /management/v1/licenses Manage licenses Requires licenses.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code. ## Request format - Version/group: **management** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `action` | No / conditional | string | Action to perform in that module. Allowed: "create", "edit", "delete", "ban", "unban", "pause", "resume", "extend", "shorten", "reset_sid" Default: "create" | | `appId` | No / conditional | string | Application ID. Required for app-scoped changes. | | `id` | No / conditional | string | Record ID. Required for actions other than create. | | `days` | No / conditional | integer | Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened. Minimum: 1 Maximum: 365000 | | `values` | No / conditional | object | Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/management/v1/licenses' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \ --data-raw '{ "action": "create", "appId": "YOUR_APP_ID", "values": { "subscription": "Default", "expiryDays": "30", "devices": "1" } }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: GET /management/v1/devices # GET /management/v1/devices List devices Requires devices.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination. ## Request format - Version/group: **management** (rebuild beta) - Input location: **URL query parameters**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send no request body. JSON response content does not mean a GET request needs a JSON body. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters | Parameter | Required | Type | Meaning | | --- | --- | --- | --- | | `appId` | No | string | Application record ID; optional for listing. | | `limit` | No | integer | Default: 1000 Minimum: 1 Maximum: 1000 | | `offset` | No | integer | Default: 0 Minimum: 0 Maximum: 100000 | URL-encode values. New integrations must keep credentials in Authorization headers; the legacy Elite Key GET route above is a compatibility exception. ## Body fields None. This handler does not use a GET JSON body for filters. ## Request example Replace placeholder values before sending. ```bash curl -X GET 'http://127.0.0.1:4000/management/v1/devices?appId=YOUR_APP_ID&limit=1000&offset=0' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /management/v1/devices # POST /management/v1/devices Manage devices Requires devices.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code. ## Request format - Version/group: **management** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `action` | No / conditional | string | Action to perform in that module. Allowed: "create", "edit", "delete", "ban", "unban", "pause", "resume", "extend", "shorten", "reset_sid" Default: "create" | | `appId` | No / conditional | string | Application ID. Required for app-scoped changes. | | `id` | No / conditional | string | Record ID. Required for actions other than create. | | `days` | No / conditional | integer | Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened. Minimum: 1 Maximum: 365000 | | `values` | No / conditional | object | Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/management/v1/devices' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \ --data-raw '{ "action": "create", "appId": "YOUR_APP_ID", "values": { "name": "YOUR_RECORD_NAME" } }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: GET /management/v1/subscriptions # GET /management/v1/subscriptions List plans Requires subscriptions.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination. ## Request format - Version/group: **management** (rebuild beta) - Input location: **URL query parameters**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send no request body. JSON response content does not mean a GET request needs a JSON body. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters | Parameter | Required | Type | Meaning | | --- | --- | --- | --- | | `appId` | No | string | Application record ID; optional for listing. | | `limit` | No | integer | Default: 1000 Minimum: 1 Maximum: 1000 | | `offset` | No | integer | Default: 0 Minimum: 0 Maximum: 100000 | URL-encode values. New integrations must keep credentials in Authorization headers; the legacy Elite Key GET route above is a compatibility exception. ## Body fields None. This handler does not use a GET JSON body for filters. ## Request example Replace placeholder values before sending. ```bash curl -X GET 'http://127.0.0.1:4000/management/v1/subscriptions?appId=YOUR_APP_ID&limit=1000&offset=0' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /management/v1/subscriptions # POST /management/v1/subscriptions Manage plans Requires subscriptions.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code. ## Request format - Version/group: **management** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `action` | No / conditional | string | Action to perform in that module. Allowed: "create", "edit", "delete" Default: "create" | | `appId` | No / conditional | string | Application ID. Required for app-scoped changes. | | `id` | No / conditional | string | Record ID. Required for actions other than create. | | `days` | No / conditional | integer | Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened. Minimum: 1 Maximum: 365000 | | `values` | No / conditional | object | Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/management/v1/subscriptions' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \ --data-raw '{ "action": "create", "appId": "YOUR_APP_ID", "values": { "name": "YOUR_RECORD_NAME" } }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: GET /management/v1/variables # GET /management/v1/variables List cloud variables Requires variables.info. Results are scoped to the key owner. Secret-like fields are omitted. Use appId to limit the result to one application. This API uses offset pagination. ## Request format - Version/group: **management** (rebuild beta) - Input location: **URL query parameters**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send no request body. JSON response content does not mean a GET request needs a JSON body. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters | Parameter | Required | Type | Meaning | | --- | --- | --- | --- | | `appId` | No | string | Application record ID; optional for listing. | | `limit` | No | integer | Default: 1000 Minimum: 1 Maximum: 1000 | | `offset` | No | integer | Default: 0 Minimum: 0 Maximum: 100000 | URL-encode values. New integrations must keep credentials in Authorization headers; the legacy Elite Key GET route above is a compatibility exception. ## Body fields None. This handler does not use a GET JSON body for filters. ## Request example Replace placeholder values before sending. ```bash curl -X GET 'http://127.0.0.1:4000/management/v1/variables?appId=YOUR_APP_ID&limit=1000&offset=0' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /management/v1/variables # POST /management/v1/variables Manage cloud variables Requires variables.{action}. Changes are audited. Use the record ID for edit/delete and the application ID for app-scoped records. The route accepts POST with an action, not PUT or DELETE. Do not expose management keys in distributed SDKs or browser code. ## Request format - Version/group: **management** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `action` | No / conditional | string | Action to perform in that module. Allowed: "create", "edit", "delete", "pause", "resume" Default: "create" | | `appId` | No / conditional | string | Application ID. Required for app-scoped changes. | | `id` | No / conditional | string | Record ID. Required for actions other than create. | | `days` | No / conditional | integer | Duration for extend or shorten. Deferred/lifetime expiry cannot be extended or shortened. Minimum: 1 Maximum: 365000 | | `values` | No / conditional | object | Fields for create/edit. Use name for app/identity/value names, subscription for an app plan name, expiryDays for duration or Lifetime, devices for device limit, and value for cloud variable content. Application creation requires name; version defaults to 1.0.0. License creation can omit name to generate a key; keyGroups/keyLength default to 4, each allows 3 to 5. Status changes require their own action permissions. | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/management/v1/variables' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \ --data-raw '{ "action": "create", "appId": "YOUR_APP_ID", "values": { "name": "YOUR_RECORD_NAME" } }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Endpoint README: POST /bots/v1/commands # POST /bots/v1/commands Run a bot command Requires a Bot Key with the corresponding management scope. Elite Keys are rejected here. apps lists up to 30 apps; status shows one app; license creates a Default-plan key; pause/resume control an app; ban/unban control a user, license or device. ## Request format - Version/group: **management** (rebuild beta) - Input location: **JSON body**. - Base URL: `http://127.0.0.1:4000`. - Response fields and HTTP errors follow this version, not another version's SDK. Send `Content-Type: application/json`. Put operation fields in the JSON body. Do not move them into the URL. ## Authentication and headers Use `Authorization: Bearer ACCOUNT_KEY`. This must be an entitled, unexpired account-level key with the required permissions. Use a Bot Key on the bot-command endpoint. Never distribute management credentials in an application SDK. ## URL parameters None are part of this endpoint contract. A query string is not an alternative source for the body fields. ## Body fields | Field | Required | Type | Meaning and limits | | --- | --- | --- | --- | | `command` | Yes | string | Allowed: "apps", "status", "license", "pause", "resume", "ban", "unban" | | `appId` | No / conditional | string | Application ID, required except for apps. | | `resource` | No / conditional | string | Required for ban and unban. Allowed: "users", "licenses", "devices" | | `id` | No / conditional | string | Identity record ID for ban/unban. | | `days` | No / conditional | string | License duration when command is license. Default: "30" | ## Request example Replace placeholder values before sending. ```bash curl -X POST 'http://127.0.0.1:4000/bots/v1/commands' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_ACCOUNT_KEY' \ --data-raw '{ "command": "status", "appId": "d52d697c-490e-4d0e-bbea-0884f2db409c" }' ``` ## HTTP responses | Status | Meaning | | --- | --- | | 200 | Successful | | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 429 | Too many requests | Use the documented HTTP status and response fields; check success/error fields where that version provides them. Do not retry state-changing operations blindly. Request-format policy and endpoint index # Complete C# V3 SDK source ```csharp // AuthlyX C# SDK Version 3.0 BETA using System.Collections.Generic; using System.Diagnostics; using System.Globalization; using System.IO; using System.Linq; using System.Net.Http.Headers; using System.Net.Http; using System.Security.Cryptography; using System.Text; using System.Threading.Tasks; using System.Threading; using System; using Newtonsoft.Json.Linq; using Newtonsoft.Json; using Org.BouncyCastle.Crypto.Parameters; using Org.BouncyCastle.Crypto.Signers; using Org.BouncyCastle.Security; using Org.BouncyCastle.X509; namespace AuthlyXSDK { public sealed class AuthlyX : IDisposable { private UserData currentUserData = new UserData(); public UserData user => HasAccess ? currentUserData : UserData.Empty; public UserData userData => user; private readonly ClientOptions options; private readonly IReadOnlyDictionary responseKeys, offlineKeys, scriptKeys; private readonly HttpClient http; private readonly SemaphoreSlim gate = new SemaphoreSlim(1, 1); private readonly CancellationTokenSource lifetime = new CancellationTokenSource(); private CancellationTokenSource? heartbeat; private readonly byte[] seed = Array.Empty(); private readonly AuthlyXException? storageFailure; private readonly string storageName, identityName, publicPem, installationHash; private string? token, sessionId, appId, identityId; private JObject? offline; private long serverEpoch, anchorTicks, anchorWall, deadline; private double heartbeatSeconds = 600, jitterSeconds = 15; private bool disposed, loggingOut; public event Action? ConnectionChanged; public event Action? SessionInvalidated; public ConnectionState Connection { get; private set; } = ConnectionState.Disconnected; #if NET8_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif public AuthlyX(string appKey, string version, TimeSpan? requestTimeout = null, int retryLimit = 2, bool debug = false, string? api = null, string heartbeat = "server") : this(configured_options(appKey, version, requestTimeout, retryLimit, debug, api, heartbeat)) { } public static string systemId() { const string windowsAssembly = "System.Security.Principal.WindowsIdentity, System.Security.Principal.Windows"; const string frameworkAssembly = "System.Security.Principal.WindowsIdentity, mscorlib"; Type? identityType = Type.GetType(windowsAssembly, false) ?? Type.GetType(frameworkAssembly, false); if (identityType == null) { throw new PlatformNotSupportedException( "Supply a platform system ID through ClientOptions."); } var getCurrent = identityType.GetMethod("GetCurrent", Type.EmptyTypes); var identity = getCurrent?.Invoke(null, null); try { var user = identityType.GetProperty("User")?.GetValue(identity, null); var sid = user?.GetType().GetProperty("Value")?.GetValue(user, null) as string; if (sid == null || sid.Length == 0) { throw new PlatformNotSupportedException( "The current Windows account has no system ID."); } return sid; } finally { (identity as IDisposable)?.Dispose(); } } #if NET8_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif private static ClientOptions configured_options(string appKey, string version, TimeSpan? requestTimeout, int retryLimit, bool debug, string? api, string heartbeat) { if (heartbeat != "server" && heartbeat != "manual") { throw new ArgumentException("Use server or manual heartbeat mode.", nameof(heartbeat)); } var settings = defaultOptions(appKey, version); settings.RequestBudget = requestTimeout ?? TimeSpan.FromSeconds(10); settings.RetryLimit = retryLimit; settings.Debug = debug; settings.AutomaticHeartbeat = heartbeat == "server"; if (api != null) { settings.Endpoint = new Uri(api); } return settings; } #if NET8_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif public static ClientOptions defaultOptions(string appKey, string version) => new ClientOptions { AppKey = appKey, Version = version, SystemId = systemId(), Endpoint = new Uri("https://api.authlyx.dev"), AllowLocalHttp = true, Storage = new WindowsProtectedStore(Path.Combine( Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "AuthlyX", "v3")), ResponseKeys = new Dictionary< string, string> { ["2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052"] = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n" }, OfflineKeys = new Dictionary< string, string> { ["d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2"] = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n" }, ScriptKeys = new Dictionary< string, string> { ["5aec455eb0b10697"] = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n" } }; public AuthlyX(ClientOptions options) { if (options.Storage == null || options.ResponseKeys.Count == 0 || string.IsNullOrWhiteSpace(options.AppKey) || string.IsNullOrWhiteSpace(options.Version) || string.IsNullOrWhiteSpace(options.SystemId)) { throw new ArgumentException("Provide AppKey, version, system ID, protected " + "storage and trusted response keys."); } if (options.Endpoint.AbsolutePath != "/" || options.Endpoint.Query != "" || options.Endpoint.UserInfo != "" || options.Endpoint.Fragment != "" || (options.Endpoint.Scheme != "https" && !(options.AllowLocalHttp && options.Endpoint.Scheme == "http" && options.Endpoint.IsLoopback))) { throw new ArgumentException("Use an HTTPS API origin. HTTP is allowed " + "only for explicit loopback testing."); } if (options.RequestBudget.TotalMilliseconds < 100 || options.RequestBudget.TotalMilliseconds > 60000) { throw new ArgumentException( "Request budget must be between 100 ms and 60 seconds."); } if (options.RetryLimit < 0 || options.RetryLimit > 5) { throw new ArgumentOutOfRangeException(nameof(options.RetryLimit)); } this.options = new ClientOptions { AppKey = options.AppKey, Version = options.Version, SystemId = options.SystemId, BuildHash = options.BuildHash, Endpoint = options.Endpoint, Storage = options.Storage, RequestBudget = options.RequestBudget, AutomaticHeartbeat = options.AutomaticHeartbeat, RetryLimit = options.RetryLimit, Debug = options.Debug }; responseKeys = CopyKeys(options.ResponseKeys); offlineKeys = CopyKeys(options.OfflineKeys); scriptKeys = CopyKeys(options.ScriptKeys); storageName = "authlyx.v3." + Protocol.Hash(options.Endpoint.AbsoluteUri + "\n" + options.AppKey + "\n" + options.SystemId); identityName = "authlyx.v3.installation." + Protocol.Hash(options.Endpoint.AbsoluteUri + "\n" + options.SystemId); try { var saved = options.Storage.Load(identityName); seed = saved == null ? Protocol.Random(32) : Convert.FromBase64String(saved); if (seed.Length != 32) { throw new Exception(); } if (saved == null) { options.Storage.Save(identityName, Convert.ToBase64String(seed)); } publicPem = Protocol.PublicPem(seed); installationHash = Protocol.KeyId(publicPem); var cached = options.Storage.Load(storageName + ".offline"); if (cached != null) { offline = Protocol.Parse(cached); appId = (string?)offline["appId"]; identityId = (string?)offline["identityId"]; long now = WallNow(), previousWall = (long)offline["localTime"]!, trusted = (long)offline["trustedTime"]!; if (now < previousWall) { throw new Exception(); } Anchor(trusted + now - previousWall); if (!ValidOffline(false)) { ClearOffline(); } } } catch { Array.Clear(seed, 0, seed.Length); seed = Array.Empty(); publicPem = ""; installationHash = ""; offline = null; appId = null; identityId = null; serverEpoch = 0; storageFailure = new AuthlyXException( "STORAGE_INVALID", "Protected SDK state could not be read or saved.", FailureKind.Storage); } http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false }) { Timeout = Timeout.InfiniteTimeSpan }; } private static IReadOnlyDictionary CopyKeys( IReadOnlyDictionary keys) { var copy = new Dictionary(); foreach (var pair in keys) { copy.Add(pair.Key, pair.Value); } return copy; } private static long WallNow() => DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(); private void Anchor(long serverTime) { serverEpoch = serverTime; anchorTicks = Stopwatch.GetTimestamp(); anchorWall = WallNow(); } private long TrustedNow() => serverEpoch == 0 ? WallNow() : serverEpoch + (long)((Stopwatch.GetTimestamp() - anchorTicks) * 1000.0 / Stopwatch.Frequency); private void SetConnection(ConnectionState state) { if (Connection == state) { return; } Connection = state; try { ConnectionChanged?.Invoke(state); } catch { } } private void ClearOffline() { offline = null; options.Storage.Delete(storageName + ".offline"); } private void Invalidate(AuthlyXException error) { token = null; currentUserData = UserData.Empty; deadline = 0; StopHeartbeat(); try { ClearOffline(); } catch { offline = null; } try { SessionInvalidated?.Invoke(error); } catch { } } private static bool Revoked(string code) => code == "SESSION_EXPIRED" || code == "ACCESS_REVOKED" || code == "APP_PAUSED" || code == "ACCESS_EXPIRED" || code == "ACCESS_DENIED" || code == "IP_BLACKLISTED" || code == "IP_NOT_WHITELISTED" || code == "SID_BLACKLISTED" || code == "SID_NOT_WHITELISTED" || code == "VERSION_NOT_ALLOWED" || code == "HASH_NOT_ALLOWED" || code == "COUNTRY_BLOCKED" || code == "VPN_NOT_ALLOWED" || code == "DEVICE_NOT_ALLOWED" || code == "INVALID_CREDENTIALS" || code == "APP_DISABLED" || code == "IP_BLOCKED" || code == "SID_BLOCKED" || code == "UPDATE_REQUIRED" || code == "INVALID_HASH" || code == "VPN_BLOCKED" || code == "USER_BANNED" || code == "USER_SUSPENDED" || code == "USER_EXPIRED" || code == "LICENSE_BANNED" || code == "LICENSE_PAUSED" || code == "LICENSE_EXPIRED" || code == "MOTHERBOARD_BANNED" || code == "MOTHERBOARD_PAUSED" || code == "MOTHERBOARD_EXPIRED" || code == "PROCESSOR_BANNED" || code == "PROCESSOR_PAUSED" || code == "PROCESSOR_EXPIRED"; private async Task Send(string path, JObject data, bool authenticated, bool retryable, CancellationToken cancel) { if (storageFailure != null) { throw storageFailure; } if (authenticated && token == null) { throw new AuthlyXException("NOT_SIGNED_IN", "Sign in before using this feature.", FailureKind.Server); } string body = Protocol.Json(data); var timer = Stopwatch.StartNew(); using (var budget = CancellationTokenSource.CreateLinkedTokenSource(cancel, lifetime.Token)) { budget.CancelAfter(options.RequestBudget); for (int attempt = 0;; attempt++) { string nonce = Protocol.Hex(Protocol.Random(24)), timestamp = TrustedNow().ToString(CultureInfo.InvariantCulture); try { using (var request = new HttpRequestMessage( HttpMethod.Post, new Uri(options.Endpoint, path))) { request.Content = new StringContent(body, Encoding.UTF8, "application/json"); request.Headers.Add("X-AuthlyX-Nonce", nonce); if (authenticated) { request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token); request.Headers.Add("X-AuthlyX-Timestamp", timestamp); request.Headers.Add( "X-AuthlyX-Signature", Protocol.Sign(seed, Protocol.Json(Protocol.RequestProof( path, body, nonce, timestamp, token!)))); } using (var response = await http .SendAsync(request, HttpCompletionOption.ResponseHeadersRead, budget.Token) .ConfigureAwait(false)) { string text; using ( var stream = await response.Content.ReadAsStreamAsync().ConfigureAwait( false)) using (var bytes = new MemoryStream()) { var buffer = new byte[8192]; int count; while ((count = await stream .ReadAsync(buffer, 0, buffer.Length, budget.Token) .ConfigureAwait(false)) > 0) { if (bytes.Length + count > 2000000) { throw new AuthlyXException( "RESPONSE_INVALID", "The server response is too large.", FailureKind.Security); } bytes.Write(buffer, 0, count); } text = Encoding.UTF8.GetString(bytes.ToArray()); } JObject outer; try { outer = Protocol.Parse(text); } catch { if ((int)response.StatusCode >= 500) { throw new AuthlyXException( "SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", FailureKind.Network, (int)response.StatusCode); } throw new AuthlyXException( "RESPONSE_INVALID", "The server response is not valid JSON.", FailureKind.Security); } if (outer["verification"] == null && (int)response.StatusCode >= 500) { throw new AuthlyXException( "SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", FailureKind.Network, (int)response.StatusCode); } var value = Protocol.VerifyResponse(outer, (int)response.StatusCode, path, body, nonce, responseKeys, out var serverTime); Anchor(serverTime.ToUnixTimeMilliseconds()); SetConnection(ConnectionState.Online); if (!(bool)value["success"]! || !response.IsSuccessStatusCode) { string code = (string)value["code"]!; int status = (int)response.StatusCode; var kind = status == 429 || status >= 500 ? FailureKind.Network : FailureKind.Server; if (retryable && attempt < options.RetryLimit && (kind == FailureKind.Network || code == "REQUEST_TIME_INVALID")) { double delay = response.Headers.RetryAfter?.Delta?.TotalMilliseconds ?? (response.Headers.RetryAfter?.Date.HasValue == true ? (response.Headers.RetryAfter.Date.Value - DateTimeOffset.UtcNow) .TotalMilliseconds : 150 * (attempt + 1)); if (delay >= 0 && timer.Elapsed.TotalMilliseconds + delay + 50 < options.RequestBudget.TotalMilliseconds) { await Task .Delay(TimeSpan.FromMilliseconds(delay), budget.Token) .ConfigureAwait(false); continue; } } throw new AuthlyXException(code, (string)value["message"]!, kind, status, (string?)value["requestId"]); } return value; } } } catch (AuthlyXException error) { if (error.Kind == FailureKind.Security) { SetConnection(ConnectionState.Untrusted); Invalidate(error); } else if (error.Kind == FailureKind.Network) { SetConnection(ConnectionState.Disconnected); } else if (authenticated && Revoked(error.Code)) { Invalidate(error); } throw; } catch (OperationCanceledException) { if (cancel.IsCancellationRequested || lifetime.IsCancellationRequested) { throw; } SetConnection(ConnectionState.Disconnected); throw new AuthlyXException( "NETWORK_TIMEOUT", "The request timed out. Try again when connected.", FailureKind.Network); } catch (HttpRequestException) { SetConnection(ConnectionState.Disconnected); if (retryable && attempt < options.RetryLimit && timer.ElapsedMilliseconds + 200 < options.RequestBudget.TotalMilliseconds) { await Task.Delay(150, budget.Token).ConfigureAwait(false); continue; } throw new AuthlyXException("NETWORK_ERROR", "Could not connect to AuthlyX.", FailureKind.Network); } } } } private async Task Execute(string path, JObject data, bool authenticated, bool retryable, CancellationToken cancel) { if (options.Debug) { System.Diagnostics.Debug.WriteLine("AuthlyX request: " + path); } if (disposed) { throw new ObjectDisposedException(nameof(AuthlyX)); } await gate.WaitAsync(cancel).ConfigureAwait(false); try { if (authenticated && deadline <= TrustedNow()) { var check = await Send("/v3/session/check", new JObject(), true, true, cancel) .ConfigureAwait(false); AcceptLease((JObject)check["data"]!); } return await Send(path, data, authenticated, retryable, cancel) .ConfigureAwait(false); } finally { gate.Release(); } } private void Complete(Func>> operation, Action> completed) { if (completed == null) { throw new ArgumentNullException(nameof(completed)); } var context = SynchronizationContext.Current; _ = Task.Run(async () => { Result result; try { result = await operation().ConfigureAwait(false); } catch (AuthlyXException error) { result = new Result { Success = false, Code = error.Code, Message = error.Message, RequestId = error.RequestId ?? "" }; } catch (OperationCanceledException) { result = new Result { Success = false, Code = "CANCELLED", Message = "The request was cancelled." }; } catch (ObjectDisposedException) { result = new Result { Success = false, Code = "CLIENT_DISPOSED", Message = "The SDK has been disposed." }; } if (context == null) { completed(result); } else { context.Post( _ => completed(result), null); } }); } public void initialize(Action> completed) => init(completed); public Task> initialize(CancellationToken cancel = default) => init(cancel); public void init(Action> completed) => Complete(() => init(), completed); public void login(string license, Action> completed) => Complete(() => login(license), completed); public void login(string username, string password, Action> completed) => Complete(() => login(username, password), completed); public void deviceLogin(Action> completed) => Complete(() => deviceLogin(), completed); public void checkSession(Action> completed) => Complete(() => checkSession(), completed); public bool hasFeature(string name) => HasAccess && userData.Features.Contains(name); public async Task> getVariable(string name, CancellationToken cancel = default) { var result = await readVariable(name, cancel).ConfigureAwait(false); return new Result { Success = result.Success, Code = result.Code, Message = result.Message, RequestId = result.RequestId, Data = result.Data.Value }; } public void getVariable(string name, Action> completed) => Complete(() => getVariable(name), completed); public Task> getScript(string name, CancellationToken cancel) => getScript(name, null, cancel); public void getScript(string name, Action> completed) => Complete(() => getScript(name), completed); public void saveOfflineAccess(Action> completed) => Complete(() => saveOfflineAccess(), completed); public void logout(Action> completed) => Complete( async () => { await logout().ConfigureAwait(false); return new Result { Success = true, Code = "SESSION_ENDED", Message = "You have signed out.", Data = new JObject() }; }, completed); public async Task> getMetadata(CancellationToken cancel = default) => Result.From(await Execute("/v3/metadata/get", new JObject(), true, true, cancel) .ConfigureAwait(false)); public void getMetadata(Action> completed) => Complete(() => getMetadata(), completed); public async Task> updateVariable(string name, string value, CancellationToken cancel = default) => Result.From(await Execute("/v3/data/set", new JObject { ["name"] = name, ["value"] = value }, true, false, cancel) .ConfigureAwait(false)); public void updateVariable(string name, string value, Action> completed) => Complete(() => updateVariable(name, value), completed); public async Task> getFeatures(CancellationToken cancel = default) => Result.From(await Execute("/v3/features/list", new JObject(), true, true, cancel) .ConfigureAwait(false)); public void getFeatures(Action> completed) => Complete(() => getFeatures(), completed); public async Task> getFeature(string name, CancellationToken cancel = default) => Result.From(await Execute("/v3/features/get", new JObject { ["name"] = name }, true, true, cancel) .ConfigureAwait(false)); public void getFeature(string name, Action> completed) => Complete(() => getFeature(name), completed); public async Task> getAllMetadata(CancellationToken cancel = default) => Result.From(await Execute("/v3/metadata/list", new JObject(), true, true, cancel) .ConfigureAwait(false)); public void getAllMetadata(Action> completed) => Complete(() => getAllMetadata(), completed); public async Task> getMetadata(string key, CancellationToken cancel = default) => Result.From(await Execute("/v3/metadata/get", new JObject { ["key"] = key }, true, true, cancel) .ConfigureAwait(false)); public void getMetadata(string key, Action> completed) => Complete(() => getMetadata(key), completed); public async Task> checkMetadata(string key, CancellationToken cancel = default) => Result.From(await Execute("/v3/metadata/check", new JObject { ["key"] = key }, true, true, cancel) .ConfigureAwait(false)); public void checkMetadata(string key, Action> completed) => Complete(() => checkMetadata(key), completed); public async Task> checkFeature(string name, CancellationToken cancel = default) => Result.From(await Execute("/v3/features/check", new JObject { ["name"] = name }, true, true, cancel) .ConfigureAwait(false)); public void checkFeature(string name, Action> completed) => Complete(() => checkFeature(name), completed); public async Task> sendWebhook(string eventName, JToken data, CancellationToken cancel = default) => Result.From(await Execute("/v3/webhooks/send", new JObject { ["event"] = eventName, ["data"] = data }, true, false, cancel) .ConfigureAwait(false)); public void sendWebhook(string eventName, JToken data, Action> completed) => Complete(() => sendWebhook(eventName, data), completed); public async Task> setMetadata(string key, JToken value, CancellationToken cancel = default) => Result.From(await Execute("/v3/metadata/set", new JObject { ["key"] = key, ["value"] = value }, true, false, cancel) .ConfigureAwait(false)); public void setMetadata(string key, JToken value, Action> completed) => Complete(() => setMetadata(key, value), completed); public async Task> init(CancellationToken cancel = default) => Result.From(await Execute("/v3/initialize", new JObject { ["appKey"] = options.AppKey, ["version"] = options.Version }, false, true, cancel) .ConfigureAwait(false)); public Task> login( string license, CancellationToken cancel = default) => this.license(license, cancel); public Task> license(string license, CancellationToken cancel = default) => Login("license", "", "", license, cancel); public Task> login(string username, string password, CancellationToken cancel = default) => Login("user", username, password, "", cancel); public Task> deviceLogin(CancellationToken cancel = default) => Login("device", "", "", "", cancel); public Task> registerUser(string username, string password, string licenseKey, CancellationToken cancel = default) => Login("register", username, password, licenseKey, cancel); public void registerUser(string username, string password, string licenseKey, Action> completed) => Complete(() => registerUser(username, password, licenseKey), completed); public async Task> changePassword(string currentPassword, string newPassword, CancellationToken cancel = default) => Result.From(await Execute("/v3/account/password", new JObject { ["currentPassword"] = currentPassword, ["newPassword"] = newPassword }, true, false, cancel) .ConfigureAwait(false)); public async Task> redeemLicense(string licenseKey, CancellationToken cancel = default) => Result.From(await Execute("/v3/licenses/redeem", new JObject { ["licenseKey"] = licenseKey }, true, false, cancel) .ConfigureAwait(false)); public async Task> log(string message, CancellationToken cancel = default) => Result.From(await Execute("/v3/logs/add", new JObject { ["message"] = message }, true, false, cancel) .ConfigureAwait(false)); public void changePassword(string currentPassword, string newPassword, Action> completed) => Complete(() => changePassword(currentPassword, newPassword), completed); public void redeemLicense(string licenseKey, Action> completed) => Complete(() => redeemLicense(licenseKey), completed); public void log(string message, Action> completed) => Complete(() => log(message), completed); private async Task> Login(string type, string username, string password, string license, CancellationToken cancel) { if (disposed) { throw new ObjectDisposedException(nameof(AuthlyX)); } await gate.WaitAsync(cancel).ConfigureAwait(false); try { if (token != null) { throw new AuthlyXException("ALREADY_SIGNED_IN", "Sign out before starting another session.", FailureKind.Server); } ClearOffline(); loggingOut = false; var challenge = (JObject)(await Send("/v3/challenge", new JObject { ["appKey"] = options.AppKey, ["installationPublicKey"] = publicPem }, false, false, cancel) .ConfigureAwait(false))["data"]!; var operation = new JObject { ["type"] = type, ["appKey"] = options.AppKey, ["version"] = options.Version, ["sid"] = options.SystemId, ["hash"] = options.BuildHash, ["username"] = username, ["password"] = password, ["licenseKey"] = license }; string signature = Protocol.Sign( seed, Protocol.Json(new JObject { ["challenge"] = challenge["payload"], ["operation"] = operation })); var request = (JObject)operation.DeepClone(); request["challengeId"] = challenge["challengeId"]; request["signature"] = signature; var value = await Send("/v3/login", request, false, false, cancel).ConfigureAwait(false); appId = (string)Protocol.Parse((string)challenge["payload"]!)["appId"]!; var data = (JObject)value["data"]!; token = (string)data["token"]!; sessionId = (string)data["sessionId"]!; identityId = (string)data["identityId"]!; ClearOffline(); AcceptLease(data); currentUserData = UserData.From(data); StartHeartbeat(); return Result.From(value); } finally { gate.Release(); } } private void AcceptLease(JObject data) { if (!DateTimeOffset.TryParse((string?)data["accessDeadline"], CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind, out var parsed) || parsed.ToUnixTimeMilliseconds() > TrustedNow() + 7200100 || parsed.ToUnixTimeMilliseconds() <= 0) { var error = new AuthlyXException( "LEASE_INVALID", "The session deadline is invalid.", FailureKind.Security); Invalidate(error); throw error; } deadline = parsed.ToUnixTimeMilliseconds(); if (data["features"] != null || data["featureValues"] != null || data["metadata"] != null) { currentUserData.UpdateAccess(data); } heartbeatSeconds = Math.Max(1, Math.Min(3600, (double?)data["heartbeatSeconds"] ?? 600)); jitterSeconds = Math.Max(0, Math.Min(15, (double?)data["jitterSeconds"] ?? 15)); } public async Task> checkSession(CancellationToken cancel = default) { await gate.WaitAsync(cancel).ConfigureAwait(false); try { var value = await Send("/v3/session/check", new JObject(), true, true, cancel) .ConfigureAwait(false); AcceptLease((JObject)value["data"]!); currentUserData.UpdateAccess((JObject)value["data"]!); return Result.From(value); } finally { gate.Release(); } } private async Task> readVariable(string name, CancellationToken cancel = default) => Result.From(await Execute("/v3/data/get", new JObject { ["name"] = name }, true, true, cancel) .ConfigureAwait(false)); public async Task> getScript(string name, int? revision = null, CancellationToken cancel = default) { var request = new JObject { ["name"] = name }; if (revision.HasValue) { request["revision"] = revision.Value; } var value = await Execute("/v3/scripts/get", request, true, true, cancel).ConfigureAwait(false); var data = (JObject)value["data"]!; try { var manifest = Protocol.Parse((string)data["signedPayload"]!); if (manifest["issuedAt"] != null || manifest["expiresAt"] != null) { if (manifest["issuedAt"]?.Type != JTokenType.Integer || manifest["expiresAt"]?.Type != JTokenType.Integer || (long)manifest["issuedAt"]! > TrustedNow() + 30000 || (long)manifest["expiresAt"]! <= TrustedNow() || (long)manifest["expiresAt"]! <= (long)manifest["issuedAt"]!) { throw new Exception(); } } if (manifest["minimumRevision"] != null && (manifest["minimumRevision"]!.Type != JTokenType.Integer || (int)manifest["revision"]! < (int)manifest["minimumRevision"]!)) { throw new Exception(); } var id = (string)manifest["keyId"]!; if (!scriptKeys.TryGetValue(id, out var pem) || !Protocol.Verify(pem, (string)data["signedPayload"]!, (string)data["signature"]!) || !JToken.DeepEquals(data["manifest"], manifest) || (string?)manifest["appId"] != appId || (string?)manifest["name"] != name || (revision.HasValue && (int?)manifest["revision"] != revision) || (string?)manifest["sha256"] != Protocol.Hash((string)data["content"]!) || (int?)manifest["bytes"] != Encoding.UTF8.GetByteCount((string)data["content"]!)) { throw new Exception(); } } catch { var error = new AuthlyXException( "SCRIPT_INVALID", "The script could not be verified.", FailureKind.Security); throw error; } return Result.From(value); } public async Task> saveOfflineAccess(CancellationToken cancel = default) { await gate.WaitAsync(cancel).ConfigureAwait(false); try { var challenge = (JObject)(await Send("/v3/offline/challenge", new JObject(), true, false, cancel) .ConfigureAwait(false))["data"]!; var proof = Protocol.Sign( seed, Protocol.Json( new JObject { ["challenge"] = challenge["payload"], ["operation"] = new JObject { ["action"] = "offlinePermit", ["sessionId"] = sessionId } })); var result = await Send("/v3/offline/permit", new JObject { ["challengeId"] = challenge["challengeId"], ["signature"] = proof }, true, false, cancel) .ConfigureAwait(false); offline = new JObject { ["appId"] = appId, ["identityId"] = identityId, ["permit"] = result["data"], ["trustedTime"] = TrustedNow(), ["localTime"] = WallNow() }; if (!ValidOffline(true)) { ClearOffline(); throw new AuthlyXException("OFFLINE_INVALID", "The offline permit could not be verified.", FailureKind.Security); } return Result.From(result); } finally { gate.Release(); } } private bool ValidOffline(bool save) { if (offline == null || appId == null || identityId == null || WallNow() < anchorWall) { return false; } try { var permit = (JObject)offline["permit"]!; string payload = (string)permit["signedPayload"]!; if (payload.Length > 4096) { return false; } var claims = Protocol.Parse(payload); string id = (string)claims["keyId"]!; if (!offlineKeys.TryGetValue(id, out var pem) || Protocol.KeyId(pem) != id || !Protocol.Verify(pem, payload, (string)permit["signature"]!)) { return false; } long now = TrustedNow(), issued = (long)claims["issuedAt"]!, expires = (long)claims["expiresAt"]!; if ((string?)claims["type"] != "authlyx.offline.v1" || (string?)claims["appId"] != appId || (string?)claims["subjectId"] != identityId || (string?)claims["installationKeyHash"] != installationHash || now < issued || now >= expires || expires <= issued || expires - issued > 2592000000L || now < (long)offline["trustedTime"]!) { return false; } if (save) { offline["trustedTime"] = now; offline["localTime"] = WallNow(); options.Storage.Save(storageName + ".offline", offline.ToString(Newtonsoft.Json.Formatting.None)); } return true; } catch { return false; } } public bool HasAccess => !disposed && !loggingOut && ((token != null && deadline > TrustedNow()) || ValidOffline(true)); public bool HasOfflineAccess => !disposed && !loggingOut && ValidOffline(true); public async Task logout(CancellationToken cancel = default) { loggingOut = true; StopHeartbeat(); await gate.WaitAsync(CancellationToken.None).ConfigureAwait(false); try { if (token != null) { await Send("/v3/session/logout", new JObject(), true, false, cancel) .ConfigureAwait(false); } } finally { StopHeartbeat(); token = null; currentUserData = UserData.Empty; deadline = 0; try { ClearOffline(); } finally { gate.Release(); } } } private void StopHeartbeat() { var old = heartbeat; heartbeat = null; if (old != null) { old.Cancel(); } } private void StartHeartbeat() { StopHeartbeat(); if (!options.AutomaticHeartbeat) { return; } var source = CancellationTokenSource.CreateLinkedTokenSource(lifetime.Token); heartbeat = source; _ = Task.Run( async () => { try { while (!source.IsCancellationRequested) { double unit = BitConverter.ToUInt32(Protocol.Random(4), 0) / (double)uint.MaxValue; await Task .Delay(TimeSpan.FromSeconds(Math.Max( 1, heartbeatSeconds + (unit * 2 - 1) * jitterSeconds)), source.Token) .ConfigureAwait(false); try { await checkSession(source.Token).ConfigureAwait(false); } catch (AuthlyXException) { if (token == null) { break; } } } } catch (OperationCanceledException) { } catch (ObjectDisposedException) { } finally { source.Dispose(); } }); } public Task> onResume(CancellationToken cancel = default) => checkSession(cancel); public void Dispose() { if (disposed) { return; } disposed = true; StopHeartbeat(); lifetime.Cancel(); token = null; currentUserData = UserData.Empty; deadline = 0; Array.Clear(seed, 0, seed.Length); http.Dispose(); SetConnection(ConnectionState.Disposed); } } public enum FailureKind { Server, Network, Security, Cancelled, Storage } public enum ConnectionState { Online, Disconnected, Untrusted, Disposed } public sealed class AuthlyXException : Exception { public string Code { get; } public string? RequestId { get; } public int Status { get; } public FailureKind Kind { get; } public AuthlyXException(string code, string message, FailureKind kind, int status = 0, string? requestId = null) : base(message) { Code = code; Kind = kind; Status = status; RequestId = requestId; } } public sealed class Result { public bool Success { get; internal set; } public string Code { get; internal set; } = ""; public string Message { get; internal set; } = ""; public string RequestId { get; internal set; } = ""; public T Data { get; internal set; } = default!; public bool ok => Success; public bool failed => !Success; public string code => Code; public string message => Message; public string requestId => RequestId; public T data => Data; public override string ToString() => Code; internal static Result From(JObject value) => new Result { Success = (bool)value["success"]!, Code = (string)value["code"]!, Message = (string)value["message"]!, RequestId = (string)value["requestId"]!, Data = value["data"]!.ToObject()! }; } public sealed class UserData { internal static readonly UserData Empty = new UserData(); public string Id { get; private set; } = ""; public string LoginType { get; private set; } = ""; public string Username { get; private set; } = ""; public string Email { get; private set; } = ""; public string LicenseKey { get; private set; } = ""; public string SID { get; private set; } = ""; public string Hwid => SID; public string Plan { get; private set; } = ""; public string Subscription => Plan; public string IpAddress { get; private set; } = ""; public string Country { get; private set; } = ""; public DateTimeOffset? ExpiryDate { get; private set; } public DateTimeOffset? RegisteredAt { get; private set; } public DateTimeOffset? LastLogin { get; private set; } public bool IsLifetime { get; private set; } public int DeviceLimit { get; private set; } public IReadOnlyList Features { get; private set; } = new List().AsReadOnly(); public IReadOnlyDictionary Metadata { get; private set; } = new System.Collections.ObjectModel.ReadOnlyDictionary( new Dictionary()); public IReadOnlyDictionary FeatureValues { get; private set; } = new System.Collections.ObjectModel.ReadOnlyDictionary( new Dictionary()); internal void UpdateAccess(JObject data) { FeatureValues = new System.Collections.ObjectModel.ReadOnlyDictionary( (data["featureValues"] as JObject ?? new JObject()) .Properties() .ToDictionary(value => value.Name, value => value.Value.Type == JTokenType.Null ? null : ((JValue)value.Value).Value)); Features = ((data["features"] as JArray) ?.Values() .Where(value => value != null) .Select(value => value!) .ToList() ?? new List()) .AsReadOnly(); Metadata = new System.Collections.ObjectModel.ReadOnlyDictionary( (data["metadata"] as JObject ?? new JObject()) .Properties() .ToDictionary(value => value.Name, value => value.Value.Type == JTokenType.Null ? null : ((JValue)value.Value).Value)); } internal UserData() { } internal static UserData From(JObject data) { var identity = data["identity"] as JObject ?? new JObject(); var type = (string?)identity["type"] ?? ""; var result = new UserData { Id = (string?)data["identityId"] ?? "", LoginType = type, Username = type == "user" ? (string?)identity["name"] ?? "" : "", LicenseKey = (string?)identity["licenseKey"] ?? (type == "license" ? (string?)identity["name"] ?? "" : ""), Email = (string?)identity["email"] ?? "", SID = (string?)identity["systemId"] ?? "", Plan = (string?)identity["plan"] ?? "", IpAddress = (string?)identity["ipAddress"] ?? "", Country = (string?)identity["country"] ?? "", ExpiryDate = Date(identity["expiry"]), RegisteredAt = Date(identity["registeredAt"]), LastLogin = Date(identity["lastLogin"]), IsLifetime = identity["expiry"] == null || identity["expiry"]!.Type == JTokenType.Null, DeviceLimit = (int?)identity["deviceLimit"] ?? 0 }; result.UpdateAccess(identity); return result; } private static DateTimeOffset? Date(JToken? value) => DateTimeOffset.TryParse((string?)value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind, out var date) ? date : (DateTimeOffset?)null; } public sealed class SessionInfo { public JObject? Identity { get; set; } public string SessionId { get; set; } = ""; public string IdentityId { get; set; } = ""; public string Application { get; set; } = ""; public DateTimeOffset ExpiresAt { get; set; } public DateTimeOffset AccessDeadline { get; set; } } public sealed class AppValue { public string Name { get; set; } = ""; public string Value { get; set; } = ""; } internal static class Protocol { public static JObject Parse(string text) { using (var reader = new JsonTextReader( new StringReader(text)) { DateParseHandling = DateParseHandling.None }) { return JObject.Load(reader); } } public static string Json(JToken value) { switch (value.Type) { case JTokenType.Object: return "{" + string.Join(",", ((JObject)value) .Properties() .Select(p => Quote(p.Name) + ":" + Json(p.Value))) + "}"; case JTokenType.Array: return "[" + string.Join(",", ((JArray)value).Select(Json)) + "]"; case JTokenType.String: return Quote((string)value!); case JTokenType.Boolean: return (bool)value ? "true" : "false"; case JTokenType.Null: return "null"; case JTokenType.Integer: return ((JValue)value).Value!.ToString()!; default: throw new ArgumentException("Only strings, integers, booleans, null, arrays and " + "objects are supported in protocol requests."); } } private static string Quote(string value) { var b = new StringBuilder("\""); for (int i = 0; i < value.Length; i++) { char c = value[i]; switch (c) { case '"': b.Append("\\\""); break; case '\\': b.Append("\\\\"); break; case '\b': b.Append("\\b"); break; case '\f': b.Append("\\f"); break; case '\n': b.Append("\\n"); break; case '\r': b.Append("\\r"); break; case '\t': b.Append("\\t"); break; default: if (c < 32 || (char.IsSurrogate(c) && !(char.IsHighSurrogate(c) && i + 1 < value.Length && char.IsLowSurrogate(value[i + 1])))) { b.Append("\\u").Append( ((int)c).ToString("x4", CultureInfo.InvariantCulture)); } else { b.Append(c); if (char.IsHighSurrogate(c)) { b.Append(value[++i]); } } break; } } return b.Append('"').ToString(); } public static string Hash(byte[] value) { using (var sha = SHA256.Create()) { return Hex(sha.ComputeHash(value)); } } public static string Hash(string value) => Hash(Encoding.UTF8.GetBytes(value)); public static string Hex(byte[] value) => BitConverter.ToString(value).Replace("-", "").ToLowerInvariant(); public static byte[] Random(int length) { var bytes = new byte[length]; using (var rng = RandomNumberGenerator.Create()) { rng.GetBytes(bytes); } return bytes; } public static string PublicPem(byte[] seed) { var der = SubjectPublicKeyInfoFactory .CreateSubjectPublicKeyInfo( new Ed25519PrivateKeyParameters(seed, 0).GeneratePublicKey()) .GetEncoded(); return "-----BEGIN PUBLIC KEY-----\n" + Convert.ToBase64String(der) + "\n-----END PUBLIC KEY-----\n"; } public static byte[] PublicDer(string pem) => Convert.FromBase64String(pem.Replace("-----BEGIN PUBLIC KEY-----", "") .Replace("-----END PUBLIC KEY-----", "") .Trim()); public static string KeyId(string pem) => Hash(PublicDer(pem)); public static string Sign(byte[] seed, string payload) { var signer = new Ed25519Signer(); signer.Init(true, new Ed25519PrivateKeyParameters(seed, 0)); var bytes = Encoding.UTF8.GetBytes(payload); signer.BlockUpdate(bytes, 0, bytes.Length); return Convert.ToBase64String(signer.GenerateSignature()); } public static bool Verify(string pem, string payload, string signature) { try { var key = PublicKeyFactory.CreateKey(PublicDer(pem)) as Ed25519PublicKeyParameters; if (key == null) { return false; } var verifier = new Ed25519Signer(); verifier.Init(false, key); var bytes = Encoding.UTF8.GetBytes(payload); verifier.BlockUpdate(bytes, 0, bytes.Length); return verifier.VerifySignature(Convert.FromBase64String(signature)); } catch { return false; } } public static JObject RequestProof(string path, string body, string nonce, string timestamp, string token) => new JObject { ["type"] = "authlyx.request.v3", ["method"] = "POST", ["path"] = path, ["bodySha256"] = Hash(body), ["nonce"] = nonce, ["timestamp"] = timestamp, ["tokenHash"] = Hash(token) }; public static JObject VerifyResponse(JObject outer, int status, string path, string body, string nonce, IReadOnlyDictionary keys, out DateTimeOffset serverTime) { serverTime = default; try { var proof = (JObject)outer["verification"]!; string id = (string)proof["keyId"]!, payload = (string)proof["signedPayload"]!; if (payload.Length > 2000000 || !keys.TryGetValue(id, out var pem) || KeyId(pem) != id || !Verify(pem, payload, (string)proof["signature"]!)) { throw new Exception(); } var signed = Parse(payload); var request = (JObject) signed["request"]!; var envelope = (JObject)outer.DeepClone(); envelope.Remove("verification"); if ((string?) signed["type"] != "authlyx.response.v3" || (string?) signed["keyId"] != id || (int?) signed["httpStatus"] != status || (string?)request["method"] != "POST" || (string?)request["path"] != path || (string?)request["nonce"] != nonce || (string?)request["bodySha256"] != Hash(body) || !JToken.DeepEquals(signed["response"], envelope) || envelope["message"]?.Type != JTokenType.String || envelope["success"]?.Type != JTokenType.Boolean || envelope["code"]?.Type != JTokenType.String || envelope["requestId"]?.Type != JTokenType.String) { throw new Exception(); } serverTime = DateTimeOffset.Parse((string) signed["serverTime"]!, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind); return (JObject) signed["response"]!; } catch { throw new AuthlyXException("RESPONSE_INVALID", "The server response could not be verified.", FailureKind.Security); } } } public interface IProtectedStore { string? Load(string name); void Save(string name, string value); void Delete(string name); } #if NET8_0_OR_GREATER [System.Runtime.Versioning.SupportedOSPlatform("windows")] #endif public sealed class WindowsProtectedStore : IProtectedStore { private readonly string directory; public WindowsProtectedStore(string directory) { this.directory = Path.GetFullPath(directory); Directory.CreateDirectory(this.directory); } private string FileName(string name) => Path.Combine(directory, Protocol.Hash(name) + ".dat"); public string? Load(string name) { var path = FileName(name); if (!File.Exists(path)) { return null; } var value = File.ReadAllBytes(path); if (value.Length > 1048576) { throw new IOException("Protected state is too large."); } return Encoding.UTF8.GetString(ProtectedData.Unprotect( value, Encoding.UTF8.GetBytes(name), DataProtectionScope.CurrentUser)); } public void Save(string name, string value) { var path = FileName(name); var temp = path + "." + Guid.NewGuid().ToString("N") + ".tmp"; try { var bytes = ProtectedData.Protect(Encoding.UTF8.GetBytes(value), Encoding.UTF8.GetBytes(name), DataProtectionScope.CurrentUser); using (var stream = new FileStream(temp, FileMode.CreateNew, FileAccess.Write, FileShare.None)) { stream.Write(bytes, 0, bytes.Length); stream.Flush(true); } if (File.Exists(path)) { File.Replace(temp, path, null); } else { File.Move(temp, path); } } finally { if (File.Exists(temp)) { File.Delete(temp); } } } public void Delete(string name) { var path = FileName(name); if (File.Exists(path)) { File.Delete(path); } } } public sealed class MemoryStore : IProtectedStore { private readonly Dictionary values = new Dictionary(); public string? Load(string name) { lock (values) { return values.TryGetValue(name, out var value) ? value : null; } } public void Save(string name, string value) { lock (values) { values[name] = value; } } public void Delete(string name) { lock (values) { values.Remove(name); } } } public sealed class ClientOptions { public string AppKey { get; set; } = ""; public string Version { get; set; } = ""; public string SystemId { get; set; } = ""; public string BuildHash { get; set; } = ""; public Uri Endpoint { get; set; } = new Uri("https://api.authlyx.dev"); public IReadOnlyDictionary ResponseKeys { get; set; } = new Dictionary(); public IReadOnlyDictionary OfflineKeys { get; set; } = new Dictionary(); public IReadOnlyDictionary ScriptKeys { get; set; } = new Dictionary(); public IProtectedStore Storage { get; set; } = null!; public TimeSpan RequestBudget { get; set; } = TimeSpan.FromSeconds(8); public bool AutomaticHeartbeat { get; set; } = true; public int RetryLimit { get; set; } = 2; public bool Debug { get; set; } public bool AllowLocalHttp { get; set; } } } ``` # Complete C++ V3 SDK source ```cpp // AuthlyX C++ SDK Version 3.0 BETA #pragma once #ifndef NOMINMAX #define NOMINMAX #endif #ifdef min #undef min #endif #ifdef max #undef max #endif #include #include #include #include #include #include #include #include #include #include #include #include #include #include #ifndef NOMINMAX #define NOMINMAX #endif #include #include #include #include #include #include #include #include #include #include #include #include #include #include #ifdef _WIN32 #ifndef WIN32_LEAN_AND_MEAN #define WIN32_LEAN_AND_MEAN #endif #include #include #include #endif namespace authlyx { using json = nlohmann::ordered_json; class error : public std::runtime_error { public: std::string code, kind, request_id; int status; error(std::string code, std::string message, std::string kind, int status = 0, std::string request_id = ""); }; struct result { bool success; bool ok() const { return success; } bool failed() const { return !success; } std::string code, message, request_id; json data; template T decode() const { return data.template get(); } }; class protected_store { public: virtual ~protected_store() = default; virtual std::optional load(const std::string &) = 0; virtual void save(const std::string &, const std::string &) = 0; virtual void remove(const std::string &) = 0; }; class memory_store final : public protected_store { std::mutex mutex_; std::map values_; public: std::optional load(const std::string &) override; void save(const std::string &, const std::string &) override; void remove(const std::string &) override; }; class windows_protected_store final : public protected_store { std::filesystem::path directory_; std::filesystem::path file(const std::string &) const; public: explicit windows_protected_store(std::filesystem::path); std::optional load(const std::string &) override; void save(const std::string &, const std::string &) override; void remove(const std::string &) override; }; struct options { std::string app_key, version, systemId, endpoint, build_hash; std::map response_keys, offline_keys, script_keys; std::shared_ptr storage; std::chrono::milliseconds request_budget{8000}; bool manual_heartbeat = false, allow_local_http = false; std::string heartbeat; std::function on_connection; std::function on_invalidated; }; class AuthlyX final { struct impl; std::shared_ptr impl_; std::future execute(std::function, std::stop_token); public: explicit AuthlyX(options); AuthlyX(std::string app_key, std::string version); static std::string systemId(); ~AuthlyX(); AuthlyX(const AuthlyX &) = delete; AuthlyX &operator=(const AuthlyX &) = delete; json userData() const; std::future registerUser(std::string, std::string, std::string, std::stop_token = {}); std::future changePassword(std::string, std::string, std::stop_token = {}); std::future redeemLicense(std::string, std::stop_token = {}); std::future log(std::string, std::stop_token = {}); std::future initialize(std::stop_token cancel = {}) { return init(cancel); } std::future initialize(std::function callback, std::stop_token cancel = {}) { return init(std::move(callback), cancel); } std::future init(std::stop_token = {}); std::future init(std::function, std::stop_token = {}); std::future login(std::string, std::function, std::stop_token = {}); std::future login(std::string, std::string, std::function, std::stop_token = {}); std::future getVariable(std::string, std::function, std::stop_token = {}); std::future getScript(std::string, std::function, std::stop_token = {}); std::future login(std::string username, std::string password, std::stop_token = {}); std::future login(std::string license, std::stop_token = {}); std::future licenseLogin(std::string, std::stop_token = {}); std::future deviceLogin(std::stop_token = {}); std::future checkSession(std::stop_token = {}); std::future onResume(std::stop_token = {}); std::future getMetadata(std::stop_token = {}); std::future updateVariable(std::string name, std::string value, std::stop_token = {}); std::future getFeatures(std::stop_token = {}); std::future getFeature(std::string name, std::stop_token = {}); std::future getAllMetadata(std::stop_token = {}); std::future getMetadata(std::string key, std::stop_token = {}); std::future checkMetadata(std::string key, std::stop_token = {}); std::future sendWebhook(std::string event_name, json data, std::stop_token = {}); std::future setMetadata(std::string, json, std::stop_token = {}); std::future checkFeature(std::string, std::stop_token = {}); std::future getVariable(std::string, std::stop_token = {}); std::future getScript(std::string, std::optional = {}, std::stop_token = {}); std::future saveOfflineAccess(std::stop_token = {}); bool hasAccess(); bool hasOfflineAccess(); std::future logout(std::stop_token = {}); void close(); }; } // namespace authlyx namespace authlyx { using namespace std::chrono; inline error::error(std::string c, std::string m, std::string k, int s, std::string id) : std::runtime_error(std::move(m)), code(std::move(c)), kind(std::move(k)), request_id(std::move(id)), status(s) { } namespace detail { inline long long wall() { return duration_cast(system_clock::now().time_since_epoch()).count(); } inline std::string hex(const unsigned char *bytes, std::size_t size) { std::ostringstream out; out << std::hex << std::setfill('0'); for (std::size_t i = 0; i < size; ++i) out << std::setw(2) << static_cast(bytes[i]); return out.str(); } inline std::string hash(const std::string &value) { unsigned char output[SHA256_DIGEST_LENGTH]; SHA256(reinterpret_cast(value.data()), value.size(), output); return hex(output, sizeof output); } inline std::string random(std::size_t n) { std::string bytes(n, '\0'); if (RAND_bytes(reinterpret_cast(bytes.data()), static_cast(n)) != 1) throw error("RANDOM_UNAVAILABLE", "The OS random source is unavailable.", "security"); return bytes; } inline std::string b64(const std::string &v) { std::string out(4 * ((v.size() + 2) / 3), '\0'); EVP_EncodeBlock(reinterpret_cast(out.data()), reinterpret_cast(v.data()), static_cast(v.size())); return out; } inline std::string unb64(const std::string &v) { if (v.empty() || v.size() % 4) throw error("DATA_INVALID", "Invalid base64 data.", "security"); std::string out(v.size() / 4 * 3, '\0'); int length = EVP_DecodeBlock(reinterpret_cast(out.data()), reinterpret_cast(v.data()), static_cast(v.size())); if (length < 0) throw error("DATA_INVALID", "Invalid base64 data.", "security"); if (v.back() == '=') --length; if (v.size() > 1 && v[v.size() - 2] == '=') --length; out.resize(length); return out; } using pkey = std::unique_ptr; inline pkey public_key(const std::string &pem) { BIO *bio = BIO_new_mem_buf(pem.data(), static_cast(pem.size())); if (!bio) return {nullptr, EVP_PKEY_free}; auto *key = PEM_read_bio_PUBKEY(bio, nullptr, nullptr, nullptr); BIO_free(bio); if (key && EVP_PKEY_id(key) != EVP_PKEY_ED25519) { EVP_PKEY_free(key); key = nullptr; } return {key, EVP_PKEY_free}; } inline std::string der(EVP_PKEY *key) { int size = i2d_PUBKEY(key, nullptr); if (size <= 0) throw error("KEY_INVALID", "Invalid verification key.", "security"); std::string out(size, '\0'); auto *ptr = reinterpret_cast(out.data()); i2d_PUBKEY(key, &ptr); return out; } inline std::string key_id(const std::string &pem) { auto key = public_key(pem); return key ? hash(der(key.get())) : ""; } inline bool verify(const std::string &pem, const std::string &payload, const std::string &signature) { try { auto key = public_key(pem); if (!key) return false; auto sig = unb64(signature); std::unique_ptr ctx(EVP_MD_CTX_new(), EVP_MD_CTX_free); return ctx && EVP_DigestVerifyInit(ctx.get(), nullptr, nullptr, nullptr, key.get()) == 1 && EVP_DigestVerify( ctx.get(), reinterpret_cast(sig.data()), sig.size(), reinterpret_cast(payload.data()), payload.size()) == 1; } catch (...) { return false; } } inline std::string str(const json &v, const char *k) { return v.contains(k) && v[k].is_string() ? v[k].get() : ""; } inline std::string find_key(const std::map &keys, const std::string &id) { auto it = keys.find(id); return it == keys.end() ? "" : it->second; } inline bool equivalent(const json &a, const json &b) { return nlohmann::json::parse(a.dump()) == nlohmann::json::parse(b.dump()); } inline long long timestamp(const std::string &v) { std::tm time{}; std::istringstream in(v.substr(0, 19)); in >> std::get_time(&time, "%Y-%m-%dT%H:%M:%S"); if (in.fail() || v.size() < 20 || v.back() != 'Z') throw error("RESPONSE_INVALID", "Invalid server timestamp.", "security"); #ifdef _WIN32 auto seconds = _mkgmtime(&time); #else auto seconds = timegm(&time); #endif long long fraction = 0; if (v[19] == '.') { auto end = v.find('Z', 20); std::string digits = v.substr(20, end - 20); while (digits.size() < 3) digits += '0'; fraction = std::stoll(digits.substr(0, 3)); } return seconds * 1000LL + fraction; } inline std::string protect(const std::string &name, const std::string &value, bool encrypt) { #ifdef _WIN32 DATA_BLOB input{static_cast(value.size()), reinterpret_cast(const_cast(value.data()))}, entropy{static_cast(name.size()), reinterpret_cast(const_cast(name.data()))}, output{}; BOOL ok = encrypt ? CryptProtectData(&input, nullptr, &entropy, nullptr, nullptr, CRYPTPROTECT_UI_FORBIDDEN, &output) : CryptUnprotectData(&input, nullptr, &entropy, nullptr, nullptr, CRYPTPROTECT_UI_FORBIDDEN, &output); if (!ok) throw error("STORAGE_INVALID", "Protected state could not be read or saved.", "storage"); std::string bytes(reinterpret_cast(output.pbData), output.cbData); LocalFree(output.pbData); return bytes; #else throw error("STORAGE_UNAVAILABLE", "Supply a platform-protected store.", "storage"); #endif } } // namespace detail using namespace detail; inline std::optional memory_store::load(const std::string &name) { std::lock_guard lock(mutex_); auto it = values_.find(name); if (it == values_.end()) return {}; return it->second; } inline void memory_store::save(const std::string &name, const std::string &v) { std::lock_guard lock(mutex_); values_[name] = v; } inline void memory_store::remove(const std::string &name) { std::lock_guard lock(mutex_); values_.erase(name); } inline windows_protected_store::windows_protected_store(std::filesystem::path path) : directory_(std::filesystem::absolute(path)) { #ifndef _WIN32 throw error("STORAGE_UNAVAILABLE", "Supply a platform-protected store.", "storage"); #endif std::filesystem::create_directories(directory_); } inline std::filesystem::path windows_protected_store::file(const std::string &name) const { return directory_ / (hash(name) + ".dat"); } inline std::optional windows_protected_store::load(const std::string &name) { auto path = file(name); if (!std::filesystem::exists(path)) return {}; if (std::filesystem::file_size(path) > 1048576) throw error("STORAGE_INVALID", "Protected state is too large.", "storage"); std::ifstream stream(path, std::ios::binary); std::string bytes((std::istreambuf_iterator(stream)), {}); return protect(name, bytes, false); } inline void windows_protected_store::save(const std::string &name, const std::string &value) { auto path = file(name), temp = path; auto bytes = random(8); temp += hex(reinterpret_cast(bytes.data()), bytes.size()) + ".tmp"; try { std::ofstream stream(temp, std::ios::binary | std::ios::trunc); std::string encrypted = protect(name, value, true); stream.write(encrypted.data(), encrypted.size()); stream.flush(); if (!stream) throw error("STORAGE_INVALID", "Could not save protected state.", "storage"); stream.close(); #ifdef _WIN32 if (!MoveFileExW(temp.c_str(), path.c_str(), MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH)) throw error("STORAGE_INVALID", "Could not replace protected state.", "storage"); #else std::filesystem::rename(temp, path); #endif } catch (...) { std::filesystem::remove(temp); throw; } } inline void windows_protected_store::remove(const std::string &name) { std::filesystem::remove(file(name)); } struct AuthlyX::impl : std::enable_shared_from_this { options o; pkey key{nullptr, EVP_PKEY_free}; json userData = json::object(); std::string public_pem, key_hash, prefix, token, session_id, app_id, identity_id; json offline; std::mutex gate, event_gate, schedule_gate; std::condition_variable condition; std::vector> events; std::thread worker; std::atomic disposed{false}, active{false}, logging_out{false}; long long server = 0, anchor_wall = 0, deadline = 0; steady_clock::time_point anchor; std::atomic heartbeat_seconds{600}, jitter_seconds{15}; explicit impl(options options) : o(std::move(options)) { if (!o.heartbeat.empty()) { if (o.heartbeat != "server" && o.heartbeat != "manual") throw std::invalid_argument("Use server or manual heartbeat mode."); o.manual_heartbeat = o.heartbeat == "manual"; } static const int initialized = []() { return curl_global_init(CURL_GLOBAL_DEFAULT); }(); if (initialized != CURLE_OK) throw error("CONFIG_INVALID", "Could not initialize HTTPS.", "network"); CURLU *url = curl_url(); if (!url || curl_url_set(url, CURLUPART_URL, o.endpoint.c_str(), 0) != CURLUE_OK) { if (url) curl_url_cleanup(url); throw error("CONFIG_INVALID", "Invalid API origin.", "storage"); } auto part = [&](CURLUPart name) { char *raw = nullptr; auto result = curl_url_get(url, name, &raw, 0); std::string value = result == CURLUE_OK ? raw : ""; curl_free(raw); return value; }; auto scheme = part(CURLUPART_SCHEME), host = part(CURLUPART_HOST), path = part(CURLUPART_PATH); bool local = host == "localhost" || host == "127.0.0.1" || host == "[::1]" || host == "::1"; bool valid = (scheme == "https" || (o.allow_local_http && scheme == "http" && local)) && (path.empty() || path == "/") && part(CURLUPART_USER).empty() && part(CURLUPART_PASSWORD).empty() && part(CURLUPART_QUERY).empty() && part(CURLUPART_FRAGMENT).empty(); curl_url_cleanup(url); if (!valid || o.app_key.empty() || o.version.empty() || o.systemId.empty() || o.response_keys.empty() || !o.storage || o.request_budget < milliseconds(100) || o.request_budget > seconds(60)) throw error("CONFIG_INVALID", "Provide an HTTPS API origin, app identity, protected " "storage, trusted keys and a bounded request budget.", "storage"); while (!o.endpoint.empty() && o.endpoint.back() == '/') o.endpoint.pop_back(); prefix = "authlyx.v3." + hash(o.endpoint + "/\n" + o.app_key + "\n" + o.systemId); auto identity_name = "authlyx.v3.installation." + hash(o.endpoint + "/\n" + o.systemId); auto saved = o.storage->load(identity_name); std::string seed = saved ? unb64(*saved) : random(32); if (seed.size() != 32) throw error("STORAGE_INVALID", "Invalid protected installation key.", "storage"); if (!saved) o.storage->save(identity_name, b64(seed)); key.reset(EVP_PKEY_new_raw_private_key( EVP_PKEY_ED25519, nullptr, reinterpret_cast(seed.data()), seed.size())); OPENSSL_cleanse(seed.data(), seed.size()); if (!key) throw error("KEY_INVALID", "Could not load installation key.", "security"); key_hash = hash(der(key.get())); BIO *bio = BIO_new(BIO_s_mem()); PEM_write_bio_PUBKEY(bio, key.get()); char *raw = nullptr; auto count = BIO_get_mem_data(bio, &raw); public_pem.assign(raw, count); BIO_free(bio); saved = o.storage->load(prefix + ".offline"); if (saved) { offline = json::parse(*saved); app_id = str(offline, "appId"); identity_id = str(offline, "identityId"); auto previous = offline.at("localTime").get(); if (wall() < previous) throw error("STORAGE_INVALID", "The local clock moved backwards.", "storage"); set_anchor(offline.at("trustedTime").get() + wall() - previous); if (!valid_offline()) clear_offline(); } } long long now() const { return server ? server + duration_cast(steady_clock::now() - anchor).count() : wall(); } void set_anchor(long long value) { server = value; anchor = steady_clock::now(); anchor_wall = wall(); } std::string sign(const std::string &value) { std::unique_ptr ctx(EVP_MD_CTX_new(), EVP_MD_CTX_free); std::string signature(64, '\0'); std::size_t size = signature.size(); if (!ctx || EVP_DigestSignInit(ctx.get(), nullptr, nullptr, nullptr, key.get()) != 1 || EVP_DigestSign(ctx.get(), reinterpret_cast(signature.data()), &size, reinterpret_cast(value.data()), value.size()) != 1) throw error("SIGNING_FAILED", "Could not sign the SDK request.", "security"); signature.resize(size); return b64(signature); } void queue(std::function fn) { std::lock_guard lock(event_gate); events.push_back(std::move(fn)); } void flush() { std::vector> pending; { std::lock_guard lock(event_gate); pending.swap(events); } for (auto &fn : pending) try { fn(); } catch (...) { } } void connection(const std::string &value) { if (o.on_connection) { auto fn = o.on_connection; queue([fn, value] { fn(value); }); } } void clear_offline() { offline = nullptr; o.storage->remove(prefix + ".offline"); } void invalidate(const error &e) { token.clear(); userData = json::object(); deadline = 0; active = false; condition.notify_all(); try { clear_offline(); } catch (...) { offline = nullptr; } if (o.on_invalidated) { auto fn = o.on_invalidated; queue([fn, e] { fn(e); }); } } result verified(const json &outer, int status, const std::string &path, const std::string &body, const std::string &nonce) { try { const auto &proof = outer.at("verification"); auto id = str(proof, "keyId"), pem = find_key(o.response_keys, id), payload = str(proof, "signedPayload"); if (payload.size() > 2000000 || pem.empty() || key_id(pem) != id || !verify(pem, payload, str(proof, "signature"))) throw std::runtime_error("invalid"); auto signed_value = json::parse(payload), envelope = outer; envelope.erase("verification"); auto request = json{{"method", "POST"}, {"path", path}, {"nonce", nonce}, {"bodySha256", hash(body)}}; if (signed_value["type"] != "authlyx.response.v3" || signed_value["keyId"] != id || signed_value["httpStatus"] != status || !equivalent(signed_value["request"], request) || !equivalent(signed_value["response"], envelope) || !envelope["message"].is_string() || !envelope["success"].is_boolean() || !envelope["code"].is_string() || !envelope["requestId"].is_string()) throw std::runtime_error("invalid"); set_anchor(timestamp(str(signed_value, "serverTime"))); return {envelope["success"].get(), str(envelope, "code"), str(envelope, "message"), str(envelope, "requestId"), envelope["data"]}; } catch (...) { throw error("RESPONSE_INVALID", "The server response could not be verified.", "security"); } } struct transfer { impl *owner; std::stop_token cancel; std::string body, retry_after; bool oversized = false; }; static std::size_t receive(char *ptr, std::size_t size, std::size_t count, void *context) { auto &t = *static_cast(context); auto n = size * count; if (t.body.size() + n > 2000000) { t.oversized = true; return 0; } t.body.append(ptr, n); return n; } static std::size_t header(char *ptr, std::size_t size, std::size_t count, void *context) { auto &t = *static_cast(context); std::string value(ptr, size * count), lower = value; for (auto &c : lower) c = static_cast(std::tolower(static_cast(c))); if (lower.starts_with("retry-after:")) { t.retry_after = value.substr(12); while (!t.retry_after.empty() && std::isspace(static_cast(t.retry_after.back()))) t.retry_after.pop_back(); while (!t.retry_after.empty() && std::isspace(static_cast(t.retry_after.front()))) t.retry_after.erase(t.retry_after.begin()); } return size * count; } static int progress(void *context, curl_off_t, curl_off_t, curl_off_t, curl_off_t) { auto &t = *static_cast(context); return t.owner->disposed || t.cancel.stop_requested() ? 1 : 0; } result request(const std::string &path, const json &data, bool auth, bool retry, std::stop_token cancel) { if (disposed || cancel.stop_requested()) throw error("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); if (auth && token.empty()) throw error("NOT_SIGNED_IN", "Sign in before using this feature.", "server"); const auto body = data.dump(); auto until = steady_clock::now() + o.request_budget; for (int attempt = 0;; ++attempt) { try { if (disposed || cancel.stop_requested()) throw error("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); auto nonce_bytes = random(24), nonce = hex(reinterpret_cast(nonce_bytes.data()), nonce_bytes.size()), stamp = std::to_string(now()); transfer t{this, cancel}; std::unique_ptr curl(curl_easy_init(), curl_easy_cleanup); if (!curl) throw error("NETWORK_ERROR", "Could not initialize HTTPS.", "network"); curl_slist *headers = nullptr; headers = curl_slist_append(headers, "Content-Type: application/json"); headers = curl_slist_append(headers, ("X-AuthlyX-Nonce: " + nonce).c_str()); if (auth) { headers = curl_slist_append(headers, ("Authorization: Bearer " + token).c_str()); headers = curl_slist_append(headers, ("X-AuthlyX-Timestamp: " + stamp).c_str()); auto proof = json{{"type", "authlyx.request.v3"}, {"method", "POST"}, {"path", path}, {"bodySha256", hash(body)}, {"nonce", nonce}, {"timestamp", stamp}, {"tokenHash", hash(token)}}; headers = curl_slist_append( headers, ("X-AuthlyX-Signature: " + sign(proof.dump())).c_str()); } std::unique_ptr list( headers, curl_slist_free_all); auto url = o.endpoint + path; curl_easy_setopt(curl.get(), CURLOPT_URL, url.c_str()); curl_easy_setopt(curl.get(), CURLOPT_HTTPHEADER, headers); curl_easy_setopt(curl.get(), CURLOPT_POST, 1L); curl_easy_setopt(curl.get(), CURLOPT_POSTFIELDS, body.data()); curl_easy_setopt(curl.get(), CURLOPT_POSTFIELDSIZE_LARGE, static_cast(body.size())); curl_easy_setopt(curl.get(), CURLOPT_FOLLOWLOCATION, 0L); curl_easy_setopt(curl.get(), CURLOPT_SSL_VERIFYPEER, 1L); curl_easy_setopt(curl.get(), CURLOPT_SSL_VERIFYHOST, 2L); curl_easy_setopt(curl.get(), CURLOPT_NOSIGNAL, 1L); auto remaining = duration_cast(until - steady_clock::now()).count(); if (remaining <= 0) throw error("NETWORK_TIMEOUT", "The request timed out.", "network"); curl_easy_setopt(curl.get(), CURLOPT_TIMEOUT_MS, static_cast(remaining)); curl_easy_setopt(curl.get(), CURLOPT_CONNECTTIMEOUT_MS, static_cast(remaining)); curl_easy_setopt(curl.get(), CURLOPT_WRITEFUNCTION, &receive); curl_easy_setopt(curl.get(), CURLOPT_WRITEDATA, &t); curl_easy_setopt(curl.get(), CURLOPT_HEADERFUNCTION, &header); curl_easy_setopt(curl.get(), CURLOPT_HEADERDATA, &t); curl_easy_setopt(curl.get(), CURLOPT_NOPROGRESS, 0L); curl_easy_setopt(curl.get(), CURLOPT_XFERINFOFUNCTION, &progress); curl_easy_setopt(curl.get(), CURLOPT_XFERINFODATA, &t); auto code = curl_easy_perform(curl.get()); if (disposed || cancel.stop_requested()) throw error("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); if (t.oversized) throw error("RESPONSE_INVALID", "The server response is too large.", "security"); if (code != CURLE_OK) throw error(code == CURLE_OPERATION_TIMEDOUT ? "NETWORK_TIMEOUT" : "NETWORK_ERROR", code == CURLE_OPERATION_TIMEDOUT ? "The request timed out. Try again when connected." : "Could not connect to AuthlyX.", "network"); long status = 0; curl_easy_getinfo(curl.get(), CURLINFO_RESPONSE_CODE, &status); json outer; try { outer = json::parse(t.body); } catch (...) { throw error(status >= 500 ? "SERVICE_UNAVAILABLE" : "RESPONSE_INVALID", status >= 500 ? "The service is temporarily unavailable." : "The server response is not valid JSON.", status >= 500 ? "network" : "security"); } if (!outer.contains("verification") && status >= 500) throw error("SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network"); auto result = verified(outer, static_cast(status), path, body, nonce); connection("online"); if (!result.success || status >= 400) { std::string kind = (status == 429 || status >= 500) ? "network" : "server"; if (retry && attempt < 2 && (kind == "network" || result.code == "REQUEST_TIME_INVALID")) { long long delay = 150; try { if (!t.retry_after.empty()) { std::size_t consumed; delay = std::stoll(t.retry_after, &consumed) * 1000; if (consumed != t.retry_after.size()) { auto seconds = curl_getdate(t.retry_after.c_str(), nullptr); delay = seconds < 0 ? o.request_budget.count() : seconds * 1000LL - wall(); } } } catch (...) { auto seconds = curl_getdate(t.retry_after.c_str(), nullptr); delay = seconds < 0 ? o.request_budget.count() : seconds * 1000LL - wall(); } if (delay >= 0 && steady_clock::now() + milliseconds(delay + 50) < until) { for (long long elapsed = 0; elapsed < delay; elapsed += 10) { if (disposed || cancel.stop_requested()) throw error("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); std::this_thread::sleep_for( milliseconds(std::min(10LL, delay - elapsed))); } continue; } } throw error(result.code, result.message, kind, static_cast(status), result.request_id); } return result; } catch (const error &e) { if (e.kind == "security") { connection("untrusted"); invalidate(e); } else if (e.kind == "network") { connection("disconnected"); if (retry && attempt < 2 && e.status == 0 && steady_clock::now() + milliseconds(200) < until) { std::this_thread::sleep_for(milliseconds(150)); continue; } } else if (auth && (e.code == "SESSION_EXPIRED" || e.code == "ACCESS_REVOKED" || e.code == "APP_PAUSED" || e.code == "ACCESS_EXPIRED" || e.code == "ACCESS_DENIED" || e.code == "IP_BLACKLISTED" || e.code == "IP_NOT_WHITELISTED" || e.code == "SID_BLACKLISTED" || e.code == "SID_NOT_WHITELISTED" || e.code == "VERSION_NOT_ALLOWED" || e.code == "HASH_NOT_ALLOWED" || e.code == "COUNTRY_BLOCKED" || e.code == "VPN_NOT_ALLOWED" || e.code == "DEVICE_NOT_ALLOWED" || e.code == "APP_DISABLED" || e.code == "IP_BLOCKED" || e.code == "SID_BLOCKED" || e.code == "UPDATE_REQUIRED" || e.code == "INVALID_HASH" || e.code == "VPN_BLOCKED" || e.code == "USER_BANNED" || e.code == "USER_SUSPENDED" || e.code == "USER_EXPIRED" || e.code == "LICENSE_BANNED" || e.code == "LICENSE_PAUSED" || e.code == "LICENSE_EXPIRED" || e.code == "MOTHERBOARD_BANNED" || e.code == "MOTHERBOARD_PAUSED" || e.code == "MOTHERBOARD_EXPIRED" || e.code == "PROCESSOR_BANNED" || e.code == "PROCESSOR_PAUSED" || e.code == "PROCESSOR_EXPIRED")) invalidate(e); throw; } } } void lease(const json &data) { auto value = timestamp(str(data, "accessDeadline")); if (value <= 0 || value > now() + 7200100) { auto e = error("LEASE_INVALID", "The session deadline is invalid.", "security"); invalidate(e); throw e; } deadline = value; for (const auto &field : {"features", "featureValues", "metadata"}) { if (data.contains(field)) userData[field] = data[field]; } heartbeat_seconds = std::clamp(data.value("heartbeatSeconds", 600.0), 1.0, 3600.0); jitter_seconds = std::clamp(data.value("jitterSeconds", 15.0), 0.0, 15.0); } result check(std::stop_token cancel) { auto r = request("/v3/session/check", json::object(), true, true, cancel); lease(r.data); return r; } result protected_call(const std::string &path, const json &data, bool retry, std::stop_token cancel) { if (!token.empty() && deadline <= now()) check(cancel); return request(path, data, true, retry, cancel); } result login(const std::string &type, const std::string &username, const std::string &password, const std::string &license, std::stop_token cancel) { if (!token.empty()) throw error("ALREADY_SIGNED_IN", "Sign out before starting another session.", "server"); clear_offline(); logging_out = false; auto challenge = request("/v3/challenge", json{{"appKey", o.app_key}, {"installationPublicKey", public_pem}}, false, false, cancel) .data; json operation = {{"type", type}, {"appKey", o.app_key}, {"version", o.version}, {"sid", o.systemId}, {"hash", o.build_hash}, {"username", username}, {"password", password}, {"licenseKey", license}}; auto signature = sign(json{{"challenge", challenge["payload"]}, {"operation", operation}}.dump()); operation["challengeId"] = challenge["challengeId"]; operation["signature"] = signature; auto r = request("/v3/login", operation, false, false, cancel); app_id = str(json::parse(str(challenge, "payload")), "appId"); token = str(r.data, "token"); session_id = str(r.data, "sessionId"); userData = r.data["identity"]; for (auto pair : {std::pair{"SID", "systemId"}, {"Email", "email"}, {"Plan", "plan"}, {"ExpiryDate", "expiry"}, {"Country", "country"}, {"IpAddress", "ipAddress"}, {"DeviceLimit", "deviceLimit"}, {"LicenseKey", "licenseKey"}}) userData[pair.first] = userData[pair.second]; userData["Username"] = userData["type"] == "user" ? userData["name"] : json(""); identity_id = str(r.data, "identityId"); lease(r.data); r.data.erase("token"); active = true; condition.notify_all(); return r; } bool valid_offline() { try { if (offline.is_null() || logging_out || disposed || wall() < anchor_wall) return false; auto permit = offline.at("permit"); auto payload = str(permit, "signedPayload"); if (payload.size() > 4096) return false; auto claims = json::parse(payload); auto id = str(claims, "keyId"), pem = find_key(o.offline_keys, id); auto issued = claims.at("issuedAt").get(), expires = claims.at("expiresAt").get(), current = now(); return !pem.empty() && key_id(pem) == id && verify(pem, payload, str(permit, "signature")) && claims["type"] == "authlyx.offline.v1" && claims["appId"] == app_id && claims["subjectId"] == identity_id && claims["installationKeyHash"] == key_hash && issued <= current && current < expires && expires > issued && expires - issued <= 2592000000LL && current >= offline.at("trustedTime").get(); } catch (...) { return false; } } bool persist_offline() { try { offline["trustedTime"] = now(); offline["localTime"] = wall(); o.storage->save(prefix + ".offline", offline.dump()); return true; } catch (...) { offline = nullptr; return false; } } void start() { if (o.manual_heartbeat) return; auto shared = shared_from_this(); worker = std::thread( [this, shared] { while (!disposed) { std::unique_lock lock(schedule_gate); condition.wait(lock, [this] { return disposed || active; }); if (disposed) return; auto bytes = random(4); unsigned number = 0; std::memcpy(&number, bytes.data(), 4); auto delay = milliseconds(static_cast( std::max(1.0, heartbeat_seconds.load() + (static_cast(number) / 0xffffffff * 2 - 1) * jitter_seconds.load()) * 1000)); if (condition.wait_for(lock, delay, [this] { return disposed || !active; })) continue; lock.unlock(); try { { std::lock_guard call(gate); if (!disposed && active) check({}); } flush(); } catch (...) { flush(); } } }); } void close() { if (disposed.exchange(true)) return; active = false; condition.notify_all(); if (worker.joinable()) { if (worker.get_id() == std::this_thread::get_id()) worker.detach(); else worker.join(); } std::lock_guard lock(gate); token.clear(); userData = json::object(); deadline = 0; } }; inline AuthlyX::AuthlyX(options o) : impl_(std::make_shared(std::move(o))) { impl_->start(); } inline AuthlyX::~AuthlyX() { close(); } inline std::future AuthlyX::execute(std::function fn, std::stop_token cancel) { auto shared = impl_; return std::async(std::launch::async, [shared, fn = std::move(fn), cancel] { try { result r; { std::lock_guard lock(shared->gate); if (shared->disposed || cancel.stop_requested()) throw error("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); r = fn(*shared, cancel); } shared->flush(); return r; } catch (...) { shared->flush(); throw; } }); } inline std::future AuthlyX::init(std::stop_token c) { return execute( [](impl &p, std::stop_token c) { return p.request("/v3/initialize", json{{"appKey", p.o.app_key}, {"version", p.o.version}}, false, true, c); }, c); } inline std::future AuthlyX::login(std::string u, std::string p, std::stop_token c) { return execute([u = std::move(u), p = std::move(p)](impl &s, std::stop_token c) { return s.login("user", u, p, "", c); }, c); } inline std::future AuthlyX::login(std::string key, std::stop_token c) { return licenseLogin(std::move(key), c); } inline std::future AuthlyX::licenseLogin(std::string key, std::stop_token c) { return execute([key = std::move(key)](impl &s, std::stop_token c) { return s.login("license", "", "", key, c); }, c); } inline std::future AuthlyX::deviceLogin(std::stop_token c) { return execute([](impl &s, std::stop_token c) { return s.login("device", "", "", "", c); }, c); } inline std::future AuthlyX::checkSession(std::stop_token c) { return execute([](impl &s, std::stop_token c) { return s.check(c); }, c); } inline std::future AuthlyX::onResume(std::stop_token c) { return checkSession(c); } inline json AuthlyX::userData() const { std::lock_guard lock(impl_->gate); return impl_->userData; } inline std::future AuthlyX::registerUser(std::string u, std::string p, std::string k, std::stop_token c) { return execute( [u = std::move(u), p = std::move(p), k = std::move(k)](impl &s, std::stop_token c) { return s.login("register", u, p, k, c); }, c); } inline std::future AuthlyX::changePassword(std::string p, std::string n, std::stop_token c) { return execute( [p = std::move(p), n = std::move(n)](impl &s, std::stop_token c) { return s.protected_call("/v3/account/password", json{{"currentPassword", p}, {"newPassword", n}}, false, c); }, c); } inline std::future AuthlyX::redeemLicense(std::string k, std::stop_token c) { return execute( [k = std::move(k)](impl &s, std::stop_token c) { return s.protected_call("/v3/licenses/redeem", json{{"licenseKey", k}}, false, c); }, c); } inline std::future AuthlyX::log(std::string m, std::stop_token c) { return execute([m = std::move(m)](impl &s, std::stop_token c) { return s.protected_call("/v3/logs/add", json{{"message", m}}, false, c); }, c); } inline std::future AuthlyX::getMetadata(std::stop_token c) { return execute([](impl &s, std::stop_token c) { return s.protected_call("/v3/metadata/get", json::object(), true, c); }, c); } inline std::future AuthlyX::updateVariable(std::string name, std::string value, std::stop_token c) { return execute( [name = std::move(name), value = std::move(value)](impl &s, std::stop_token cancel) { return s.protected_call("/v3/data/set", json{{"name", name}, {"value", value}}, false, cancel); }, c); } inline std::future AuthlyX::getFeatures(std::stop_token c) { return execute( [](impl &s, std::stop_token cancel) { return s.protected_call("/v3/features/list", json::object(), true, cancel); }, c); } inline std::future AuthlyX::getFeature(std::string name, std::stop_token c) { return execute( [name = std::move(name)](impl &s, std::stop_token cancel) { return s.protected_call("/v3/features/get", json{{"name", name}}, true, cancel); }, c); } inline std::future AuthlyX::getAllMetadata(std::stop_token c) { return execute( [](impl &s, std::stop_token cancel) { return s.protected_call("/v3/metadata/list", json::object(), true, cancel); }, c); } inline std::future AuthlyX::getMetadata(std::string key, std::stop_token c) { return execute( [key = std::move(key)](impl &s, std::stop_token cancel) { return s.protected_call("/v3/metadata/get", json{{"key", key}}, true, cancel); }, c); } inline std::future AuthlyX::checkMetadata(std::string key, std::stop_token c) { return execute( [key = std::move(key)](impl &s, std::stop_token cancel) { return s.protected_call("/v3/metadata/check", json{{"key", key}}, true, cancel); }, c); } inline std::future AuthlyX::sendWebhook(std::string event_name, json data, std::stop_token c) { return execute( [event_name = std::move(event_name), data = std::move(data)](impl &s, std::stop_token cancel) { return s.protected_call("/v3/webhooks/send", json{{"event", event_name}, {"data", data}}, false, cancel); }, c); } inline std::future AuthlyX::setMetadata(std::string key, json value, std::stop_token c) { return execute( [key = std::move(key), value = std::move(value)](impl &s, std::stop_token c) { return s.protected_call("/v3/metadata/set", json{{"key", key}, {"value", value}}, false, c); }, c); } inline std::future AuthlyX::checkFeature(std::string name, std::stop_token c) { return execute( [name = std::move(name)](impl &s, std::stop_token c) { return s.protected_call("/v3/features/check", json{{"name", name}}, true, c); }, c); } inline std::future complete(std::future operation, std::function callback) { if (!callback) throw std::invalid_argument("A completion callback is required."); std::packaged_task task( [operation = std::move(operation), callback = std::move(callback)]() mutable { result value; try { value = operation.get(); } catch (const error &failure) { value = result{false, failure.code, failure.what(), failure.request_id, nullptr}; } catch (const std::exception &failure) { value = result{false, "CLIENT_ERROR", failure.what(), "", nullptr}; } callback(std::move(value)); }); auto finished = task.get_future(); std::thread(std::move(task)).detach(); return finished; } inline std::future AuthlyX::init(std::function callback, std::stop_token cancel) { return complete(init(cancel), std::move(callback)); } inline std::future AuthlyX::login(std::string key, std::function callback, std::stop_token cancel) { return complete(login(std::move(key), cancel), std::move(callback)); } inline std::future AuthlyX::login(std::string username, std::string password, std::function callback, std::stop_token cancel) { return complete(login(std::move(username), std::move(password), cancel), std::move(callback)); } inline std::future AuthlyX::getVariable(std::string name, std::function callback, std::stop_token cancel) { return complete(getVariable(std::move(name), cancel), std::move(callback)); } inline std::future AuthlyX::getScript(std::string name, std::function callback, std::stop_token cancel) { return complete(getScript(std::move(name), std::nullopt, cancel), std::move(callback)); } inline std::future AuthlyX::getVariable(std::string name, std::stop_token c) { return execute([name = std::move(name)](impl &s, std::stop_token c) { return s.protected_call("/v3/data/get", json{{"name", name}}, true, c); }, c); } inline std::future AuthlyX::getScript(std::string name, std::optional revision, std::stop_token c) { return execute( [name = std::move(name), revision](impl &s, std::stop_token c) { json data = {{"name", name}}; if (revision) data["revision"] = *revision; auto r = s.protected_call("/v3/scripts/get", data, true, c); auto payload = str(r.data, "signedPayload"), content = str(r.data, "content"); auto manifest = json::parse(payload); if (manifest.contains("issuedAt") || manifest.contains("expiresAt")) { if (!manifest["issuedAt"].is_number_integer() || !manifest["expiresAt"].is_number_integer() || manifest["issuedAt"].get() > s.now() + 30000 || manifest["expiresAt"].get() <= s.now() || manifest["expiresAt"].get() <= manifest["issuedAt"].get()) throw error("SCRIPT_INVALID", "The script could not be verified.", "security"); } if (manifest.contains("minimumRevision") && (!manifest["minimumRevision"].is_number_integer() || manifest["revision"] < manifest["minimumRevision"])) throw error("SCRIPT_INVALID", "The script could not be verified.", "security"); auto pem = find_key(s.o.script_keys, str(manifest, "keyId")); if (pem.empty() || !verify(pem, payload, str(r.data, "signature")) || !equivalent(manifest, r.data["manifest"]) || manifest["appId"] != s.app_id || manifest["name"] != name || (revision && manifest["revision"] != *revision) || manifest["sha256"] != hash(content) || manifest["bytes"] != content.size()) throw error("SCRIPT_INVALID", "The script could not be verified.", "security"); return r; }, c); } inline std::future AuthlyX::saveOfflineAccess(std::stop_token c) { return execute( [](impl &s, std::stop_token c) { auto challenge = s.request("/v3/offline/challenge", json::object(), true, false, c).data; auto proof = s.sign(json{ {"challenge", challenge["payload"]}, {"operation", json{{"action", "offlinePermit"}, {"sessionId", s.session_id}}}} .dump()); auto r = s.request("/v3/offline/permit", json{{"challengeId", challenge["challengeId"]}, {"signature", proof}}, true, false, c); s.offline = json{{"appId", s.app_id}, {"identityId", s.identity_id}, {"permit", r.data}, {"trustedTime", s.now()}, {"localTime", wall()}}; if (!s.valid_offline()) { s.clear_offline(); throw error("OFFLINE_INVALID", "The offline permit could not be verified.", "security"); } if (!s.persist_offline()) throw error("STORAGE_INVALID", "Could not save protected offline state.", "storage"); return r; }, c); } inline bool AuthlyX::hasAccess() { std::lock_guard lock(impl_->gate); if (impl_->disposed || impl_->logging_out) return false; return (!impl_->token.empty() && impl_->deadline > impl_->now()) || (impl_->valid_offline() && impl_->persist_offline()); } inline bool AuthlyX::hasOfflineAccess() { std::lock_guard lock(impl_->gate); return impl_->valid_offline() && impl_->persist_offline(); } inline std::future AuthlyX::logout(std::stop_token c) { impl_->logging_out = true; impl_->active = false; impl_->condition.notify_all(); return execute( [c](impl &s, std::stop_token) { s.logging_out = true; try { result r{true, "SESSION_ENDED", "You have signed out.", "", nullptr}; if (!s.token.empty()) r = s.request("/v3/session/logout", json::object(), true, false, c); s.token.clear(); s.userData = json::object(); s.deadline = 0; s.clear_offline(); return r; } catch (...) { s.token.clear(); s.userData = json::object(); s.deadline = 0; s.clear_offline(); throw; } }, {}); } inline void AuthlyX::close() { if (impl_) impl_->close(); } } // namespace authlyx namespace authlyx { inline std::string AuthlyX::systemId() { #ifdef _WIN32 HANDLE token = nullptr; if (!OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &token)) throw error("SYSTEM_ID_UNAVAILABLE", "Could not read the Windows user SID.", "storage"); DWORD size = 0; GetTokenInformation(token, TokenUser, nullptr, 0, &size); std::vector buffer(size); if (!GetTokenInformation(token, TokenUser, buffer.data(), size, &size)) { CloseHandle(token); throw error("SYSTEM_ID_UNAVAILABLE", "Could not read the Windows user SID.", "storage"); } LPSTR value = nullptr; const bool valid = ConvertSidToStringSidA(reinterpret_cast(buffer.data())->User.Sid, &value); CloseHandle(token); if (!valid) throw error("SYSTEM_ID_UNAVAILABLE", "Could not read the Windows user SID.", "storage"); std::string sid(value); LocalFree(value); return sid; #else throw error("SYSTEM_ID_UNAVAILABLE", "Supply a platform system ID through options.", "storage"); #endif } inline options defaultOptions(std::string app_key, std::string version) { options o; o.app_key = std::move(app_key); o.version = std::move(version); o.systemId = AuthlyX::systemId(); o.endpoint = "https://api.authlyx.dev"; o.allow_local_http = true; #ifdef _WIN32 std::wstring local(32768, L'\0'); DWORD size = GetEnvironmentVariableW(L"LOCALAPPDATA", local.data(), static_cast(local.size())); if (!size || size >= local.size()) throw error("STORAGE_UNAVAILABLE", "LOCALAPPDATA is unavailable.", "storage"); local.resize(size); o.storage = std::make_shared(std::filesystem::path(local) / "AuthlyX" / "v3"); #else throw error("STORAGE_UNAVAILABLE", "Supply a platform-protected store through options.", "storage"); #endif o.response_keys = {{"2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052", "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n"}}; o.offline_keys = {{"d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2", "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n"}}; o.script_keys = {{"5aec455eb0b10697", "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n"}}; return o; } inline AuthlyX::AuthlyX(std::string app_key, std::string version) : AuthlyX(defaultOptions(std::move(app_key), std::move(version))) { } } // namespace authlyx namespace authlyx { using client = AuthlyX; } using AuthlyX = authlyx::AuthlyX; ``` # Complete Python V3 SDK source ```python # AuthlyX Python SDK Version 3.0 BETA import asyncio import base64 import ctypes from dataclasses import dataclass from datetime import datetime, timezone from email.utils import parsedate_to_datetime import hashlib import json import os from pathlib import Path import re import secrets import subprocess import time import threading import logging from typing import Any, Generic, Protocol, TypeVar from types import SimpleNamespace from urllib.parse import urlsplit import aiohttp from cryptography.hazmat.primitives import serialization from cryptography.hazmat.primitives.asymmetric.ed25519 import ( Ed25519PrivateKey, Ed25519PublicKey, ) class AuthlyX: def __init__(self, app_key, version, **options): self.app_key = app_key self.version = version self.callback_dispatcher = options.pop("callback_dispatcher", None) mode = options.pop("heartbeat", None) if mode is not None: if mode not in ("server", "manual"): raise ValueError("Use server or manual heartbeat mode.") options["automatic_heartbeat"] = mode == "server" for alias, native in ( ("api", "endpoint"), ("requestTimeout", "request_budget"), ("retryLimit", "retry_limit"), ): if alias in options: options[native] = options.pop(alias) self.options = options self._callback_loop = None self._callback_thread = None self._owner_loop = None self._callback_lock = threading.Lock() self._client = None self._ready_lock = asyncio.Lock() self._closed = False @staticmethod def systemId(): if os.name != "nt": raise RuntimeError("Supply a platform system ID through options.") result = subprocess.run( [ str( Path(os.environ.get("SystemRoot", "C:/Windows")) / "System32/whoami.exe" ), "/user", "/fo", "csv", "/nh", ], check=True, capture_output=True, text=True, timeout=3, creationflags=subprocess.CREATE_NO_WINDOW, ) sid = re.search(r"S-1-\d+(?:-\d+)+", result.stdout) if not sid: raise RuntimeError("Could not read the Windows user SID.") return sid.group() @staticmethod def defaults(app_key, version, **options): if "storage" not in options and not os.environ.get("LOCALAPPDATA"): raise RuntimeError("LOCALAPPDATA is unavailable.") return dict( app_key=app_key, version=version, systemId=( options["systemId"] if "systemId" in options else AuthlyX.systemId() ), endpoint="https://api.authlyx.dev", allow_local_http=True, storage=( options["storage"] if "storage" in options else WindowsProtectedStore( str(Path(os.environ["LOCALAPPDATA"]) / "AuthlyX/v3") ) ), response_keys={ "2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n" }, offline_keys={ "d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n" }, script_keys={ "5aec455eb0b10697": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n" }, ) async def _ready(self): loop = asyncio.get_running_loop() if self._owner_loop is not None and self._owner_loop is not loop: raise RuntimeError( "Use this AuthlyX instance on the event loop where it was initialized." ) async with self._ready_lock: if self._closed: raise AuthlyXError( "CLIENT_DISPOSED", "This AuthlyX instance is closed.", "cancelled" ) if self._client is None: self._owner_loop = loop defaults = await asyncio.to_thread( self.defaults, self.app_key, self.version, **self.options ) self._client = await _Runtime.create(**(defaults | self.options)) return self._client def _dispatch(self, operation, completed): if completed is None: return operation if not callable(completed): operation.close() raise TypeError("A completion callback is required.") async def finish(): try: result = await operation except asyncio.CancelledError: result = Result( False, "CANCELLED", "The request was cancelled.", None, "" ) except Exception as error: result = Result( False, getattr(error, "code", "CLIENT_ERROR"), str(error), None, getattr(error, "request_id", "") or "", ) if self.callback_dispatcher: self.callback_dispatcher(lambda: completed(result)) else: completed(result) return result if self._owner_loop is not None: loop = self._owner_loop try: if asyncio.get_running_loop() is loop: return loop.create_task(finish()) except RuntimeError: pass return asyncio.run_coroutine_threadsafe(finish(), loop) try: loop = asyncio.get_running_loop() except RuntimeError: with self._callback_lock: if self._callback_loop is None: self._callback_loop = asyncio.new_event_loop() self._callback_thread = threading.Thread( target=self._callback_loop.run_forever, daemon=True ) self._callback_thread.start() loop = self._callback_loop return asyncio.run_coroutine_threadsafe(finish(), loop) return loop.create_task(finish()) def initialize(self, completed=None): return self.init(completed) def init(self, completed=None): return self._dispatch(self._init(), completed) async def _init(self): return await (await self._ready()).init() def login(self, username_or_license, password=None, completed=None): if callable(password) and completed is None: completed, password = password, None return self._dispatch(self._login(username_or_license, password), completed) async def _login(self, username_or_license, password=None): client = await self._ready() return ( await client.licenseLogin(username_or_license) if password is None else await client.login(username_or_license, password) ) @property def userData(self): return SimpleNamespace(**(dict(self._client.userData) if self._client else {})) def registerUser(self, username, password, license_key, completed=None): async def run(): return await (await self._ready())._login( "register", username, password, license_key ) return self._dispatch(run(), completed) def changePassword(self, current_password, new_password, completed=None): return self._account_action( "/v3/account/password", {"currentPassword": current_password, "newPassword": new_password}, completed, ) def redeemLicense(self, license_key, completed=None): return self._account_action( "/v3/licenses/redeem", {"licenseKey": license_key}, completed ) def log(self, message, completed=None): return self._account_action("/v3/logs/add", {"message": message}, completed) def _account_action(self, path, data, completed): async def run(): client = await self._ready() async with client._lock: return await client._request(path, data, auth=True) return self._dispatch(run(), completed) def getVariable(self, name, completed=None): async def read(): result = await (await self._ready()).getVariable(name) return Result( result.success, result.code, result.message, result.data["value"], result.request_id, ) return self._dispatch(read(), completed) def updateVariable(self, name, value, completed=None): return self._dispatch(self.updateVariable(name, value), completed) def getFeatures(self, completed=None): return self._dispatch(self.getFeatures(), completed) def getFeature(self, name, completed=None): return self._dispatch(self.getFeature(name), completed) def getAllMetadata(self, completed=None): return self._dispatch(self.getAllMetadata(), completed) def getMetadata(self, key=None, completed=None): return self._dispatch(self.getMetadata(key), completed) def checkMetadata(self, key, completed=None): return self._dispatch(self.checkMetadata(key), completed) def checkFeature(self, name, completed=None): return self._dispatch(self.checkFeature(name), completed) def sendWebhook(self, event, data, completed=None): return self._dispatch(self.sendWebhook(event, data), completed) def getScript(self, name, completed=None): return self._dispatch(self.getScript(name), completed) async def onResume(self): return await (await self._ready()).onResume() async def hasOfflineAccess(self): return await (await self._ready()).hasOfflineAccess() async def close(self): loop = self._owner_loop if loop is not None and loop is not asyncio.get_running_loop(): await asyncio.wrap_future( asyncio.run_coroutine_threadsafe(self._close(), loop) ) else: await self._close() if self._callback_loop is not None: if self._callback_loop is asyncio.get_running_loop(): self._callback_loop.call_soon(self._callback_loop.stop) else: self._callback_loop.call_soon_threadsafe(self._callback_loop.stop) await asyncio.to_thread(self._callback_thread.join) self._callback_loop.close() self._callback_loop = None async def _close(self): async with self._ready_lock: self._closed = True if self._client: await self._client.close() async def deviceLogin(self): return await (await self._ready()).deviceLogin() async def checkSession(self): return await (await self._ready()).checkSession() async def setMetadata(self, key, value): return await (await self._ready()).setMetadata(key, value) async def saveOfflineAccess(self): return await (await self._ready()).saveOfflineAccess() async def hasAccess(self): return await (await self._ready()).hasAccess() async def logout(self): return await (await self._ready()).logout() class ProtectedStore(Protocol): async def load(self, name: str) -> str | None: ... async def save(self, name: str, value: str) -> None: ... async def delete(self, name: str) -> None: ... class MemoryStore: def __init__(self): self._data = {} async def load(self, name): return self._data.get(name) async def save(self, name, value): self._data[name] = value async def delete(self, name): self._data.pop(name, None) class WindowsProtectedStore: def __init__(self, directory: str): if os.name != "nt": raise RuntimeError( "WindowsProtectedStore requires Windows. Supply a platform-protected store." ) self.directory = Path(directory).resolve() self.directory.mkdir(parents=True, exist_ok=True) def _file(self, name): return self.directory / (hashlib.sha256(name.encode()).hexdigest() + ".dat") @staticmethod def _crypt(name, value, protect): from ctypes import wintypes class Blob(ctypes.Structure): _fields_ = [ ("size", wintypes.DWORD), ("data", ctypes.POINTER(ctypes.c_ubyte)), ] def blob(value): buffer = ctypes.create_string_buffer(value) return ( Blob(len(value), ctypes.cast(buffer, ctypes.POINTER(ctypes.c_ubyte))), buffer, ) source, keep_source = blob(value) entropy, keep_entropy = blob(name.encode()) result = Blob() crypt = ctypes.WinDLL("crypt32", use_last_error=True) kernel = ctypes.WinDLL("kernel32", use_last_error=True) kernel.LocalFree.argtypes = [ctypes.c_void_p] kernel.LocalFree.restype = ctypes.c_void_p function = crypt.CryptProtectData if protect else crypt.CryptUnprotectData function.argtypes = [ ctypes.POINTER(Blob), ctypes.c_void_p, ctypes.POINTER(Blob), ctypes.c_void_p, ctypes.c_void_p, wintypes.DWORD, ctypes.POINTER(Blob), ] function.restype = wintypes.BOOL if not function( ctypes.byref(source), None, ctypes.byref(entropy), None, None, 1, ctypes.byref(result), ): raise OSError("Protected state could not be read or saved.") try: return ctypes.string_at(result.data, result.size) finally: kernel.LocalFree(result.data) async def load(self, name): def run(): file = self._file(name) if not file.exists(): return None value = file.read_bytes() if len(value) > 1048576: raise OSError("Protected state is too large.") return self._crypt(name, value, False).decode() return await asyncio.to_thread(run) async def save(self, name, value): def run(): file = self._file(name) temp = file.with_name(file.name + "." + secrets.token_hex(8) + ".tmp") try: with temp.open("xb") as stream: stream.write(self._crypt(name, value.encode(), True)) stream.flush() os.fsync(stream.fileno()) os.replace(temp, file) finally: temp.unlink(missing_ok=True) await asyncio.to_thread(run) async def delete(self, name): await asyncio.to_thread(self._file(name).unlink, missing_ok=True) T = TypeVar("T") def compact(value): return json.dumps(value, ensure_ascii=False, separators=(",", ":"), allow_nan=False) def digest(value): return hashlib.sha256( value.encode() if isinstance(value, str) else value ).hexdigest() def key_id(key): return digest( key.public_bytes( serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo ) ) def parse_time(value): return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp() * 1000 def wall(): return int(time.time() * 1000) class AuthlyXError(Exception): def __init__(self, code, message, kind, status=0, request_id=None): super().__init__(message) self.code, self.kind, self.status, self.request_id = ( code, kind, status, request_id, ) @dataclass(repr=False) class Result(Generic[T]): success: bool code: str message: str data: T request_id: str @property def ok(self): return self.success @property def failed(self): return not self.success def __repr__(self): return f"Result({self.code!r})" @classmethod def of(cls, value): return cls( value["success"], value["code"], value["message"], value["data"], value["requestId"], ) class _Runtime: @classmethod async def create( cls, *, app_key: str, version: str, systemId: str, endpoint: str, response_keys: dict[str, str], storage: ProtectedStore, offline_keys=None, script_keys=None, build_hash="", request_budget=8.0, automatic_heartbeat=True, allow_local_http=False, on_connection=None, on_session_invalidated=None, retry_limit=2, debug=False, ): url = urlsplit(endpoint) if ( url.path not in ("", "/") or url.query or url.fragment or url.username or url.password or ( url.scheme != "https" and not ( allow_local_http and url.scheme == "http" and url.hostname in ("127.0.0.1", "localhost", "::1") ) ) ): raise ValueError( "Use an HTTPS API origin. HTTP is limited to explicit loopback testing." ) if ( not app_key or not version or not systemId or not response_keys or storage is None or not 0.1 <= request_budget <= 60 ): raise ValueError( "Provide app identity, protected storage, trusted keys and a bounded request budget." ) if ( not isinstance(retry_limit, int) or isinstance(retry_limit, bool) or not 0 <= retry_limit <= 5 ): raise ValueError("Retry limit must be between zero and five.") self = cls() self.retry_limit, self.debug = retry_limit, debug self.app_key, self.version, self.sid, self.endpoint = ( app_key, version, systemId, f"{url.scheme}://{url.netloc}", ) self.response_keys, self.offline_keys, self.script_keys = ( dict(response_keys), dict(offline_keys or {}), dict(script_keys or {}), ) self.storage, self.build_hash, self.budget, self.automatic = ( storage, build_hash, request_budget, automatic_heartbeat, ) self.on_connection, self.on_invalidated = on_connection, on_session_invalidated self._prefix = "authlyx.v3." + digest( self.endpoint + "/\n" + app_key + "\n" + systemId ) self.userData = {} self._token = self._session_id = self._app_id = self._identity_id = ( self._offline ) = None self._server = self._mono = self._wall = self._deadline = 0 self._heartbeat_seconds, self._jitter_seconds = 600, 15 self._lock, self._heartbeat, self._disposed, self._logging_out = ( asyncio.Lock(), None, False, False, ) self.connection = "disconnected" identity_name = "authlyx.v3.installation." + digest( self.endpoint + "/\n" + systemId ) try: saved = await storage.load(identity_name) seed = ( base64.b64decode(saved, validate=True) if saved else secrets.token_bytes(32) ) if len(seed) != 32: raise ValueError() if saved is None: await storage.save(identity_name, base64.b64encode(seed).decode()) self._key = Ed25519PrivateKey.from_private_bytes(seed) self._pem = ( self._key.public_key() .public_bytes( serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo, ) .decode() ) self._installation_hash = key_id(self._key.public_key()) saved = await storage.load(self._prefix + ".offline") if saved: self._offline = json.loads(saved) if wall() < self._offline["localTime"]: raise ValueError() self._app_id, self._identity_id = ( self._offline["appId"], self._offline["identityId"], ) self._anchor( self._offline["trustedTime"] + wall() - self._offline["localTime"] ) if not self._valid_offline(): await self._clear_offline() except Exception: raise AuthlyXError( "STORAGE_INVALID", "Protected SDK state could not be read or saved.", "storage", ) from None self._http = aiohttp.ClientSession( timeout=aiohttp.ClientTimeout(total=request_budget) ) return self def _anchor(self, value): self._server, self._mono, self._wall = value, time.monotonic(), wall() def _now(self): return ( int(self._server + (time.monotonic() - self._mono) * 1000) if self._server else wall() ) def _state(self, value): if self.connection == value: return self.connection = value if self.on_connection: try: self.on_connection(value) except Exception: pass async def _clear_offline(self): self._offline = None await self.storage.delete(self._prefix + ".offline") async def _invalidate(self, error): self._token, self._deadline = None, 0 self.userData = {} self._stop_heartbeat() try: await self._clear_offline() except Exception: pass if self.on_invalidated: try: self.on_invalidated(error) except Exception: pass def _verify(self, outer, status, path, body, nonce): try: proof = outer["verification"] pem = self.response_keys[proof["keyId"]] key = serialization.load_pem_public_key(pem.encode()) if ( not isinstance(key, Ed25519PublicKey) or key_id(key) != proof["keyId"] or len(proof["signedPayload"]) > 2000000 ): raise ValueError() key.verify( base64.b64decode(proof["signature"], validate=True), proof["signedPayload"].encode(), ) signed = json.loads(proof["signedPayload"]) envelope = {k: v for k, v in outer.items() if k != "verification"} if ( signed["type"] != "authlyx.response.v3" or signed["keyId"] != proof["keyId"] or signed["httpStatus"] != status or signed["request"] != { "method": "POST", "path": path, "nonce": nonce, "bodySha256": digest(body), } or signed["response"] != envelope or not isinstance(envelope["message"], str) or not isinstance(envelope["success"], bool) or not isinstance(envelope["code"], str) or not isinstance(envelope["requestId"], str) ): raise ValueError() self._anchor(parse_time(signed["serverTime"])) return signed["response"] except Exception: raise AuthlyXError( "RESPONSE_INVALID", "The server response could not be verified.", "security", ) from None async def _request(self, path, data, auth=False, retry=False): if self.debug: logging.getLogger("authlyx").debug("Request %s", path) if self._disposed: raise AuthlyXError("DISPOSED", "This client is disposed.", "cancelled") if auth and not self._token: raise AuthlyXError( "NOT_SIGNED_IN", "Sign in before using this feature.", "server" ) body, started = compact(data).encode(), time.monotonic() try: async with asyncio.timeout(self.budget): for attempt in range(self.retry_limit + 1): nonce, timestamp = secrets.token_hex(24), str(self._now()) headers = { "Content-Type": "application/json", "X-AuthlyX-Nonce": nonce, } if auth: proof = { "type": "authlyx.request.v3", "method": "POST", "path": path, "bodySha256": digest(body), "nonce": nonce, "timestamp": timestamp, "tokenHash": digest(self._token), } headers.update( { "Authorization": "Bearer " + self._token, "X-AuthlyX-Timestamp": timestamp, "X-AuthlyX-Signature": base64.b64encode( self._key.sign(compact(proof).encode()) ).decode(), } ) try: async with self._http.post( self.endpoint + path, data=body, headers=headers, allow_redirects=False, ) as response: value = bytearray() async for chunk in response.content.iter_chunked(8192): value.extend(chunk) if len(value) > 2000000: raise AuthlyXError( "RESPONSE_INVALID", "The server response is too large.", "security", ) try: outer = json.loads(value) except Exception: raise AuthlyXError( ( "SERVICE_UNAVAILABLE" if response.status >= 500 else "RESPONSE_INVALID" ), ( "The service is temporarily unavailable." if response.status >= 500 else "The server response is not valid JSON." ), "network" if response.status >= 500 else "security", response.status, ) from None if "verification" not in outer and response.status >= 500: raise AuthlyXError( "SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network", response.status, ) result = self._verify( outer, response.status, path, body, nonce ) self._state("online") if not result["success"] or response.status >= 400: kind = ( "network" if response.status == 429 or response.status >= 500 else "server" ) if ( retry and attempt < self.retry_limit and ( kind == "network" or result["code"] == "REQUEST_TIME_INVALID" ) ): after = response.headers.get("Retry-After") try: delay = ( float(after) if after and after.isdigit() else ( ( parsedate_to_datetime( after ).timestamp() - time.time() ) if after else 0.15 * (attempt + 1) ) ) except Exception: delay = self.budget if ( 0 <= delay < self.budget - (time.monotonic() - started) - 0.05 ): await asyncio.sleep(delay) continue raise AuthlyXError( result["code"], result["message"], kind, response.status, result["requestId"], ) return Result.of(result) except aiohttp.ClientError: self._state("disconnected") if ( retry and attempt < self.retry_limit and time.monotonic() - started + 0.2 < self.budget ): await asyncio.sleep(0.15) continue raise AuthlyXError( "NETWORK_ERROR", "Could not connect to AuthlyX.", "network" ) from None except TimeoutError: self._state("disconnected") raise AuthlyXError( "NETWORK_TIMEOUT", "The request timed out. Try again when connected.", "network", ) from None except AuthlyXError as error: if error.kind == "security": self._state("untrusted") await self._invalidate(error) elif error.kind == "network": self._state("disconnected") elif auth and error.code in { "SESSION_EXPIRED", "ACCESS_REVOKED", "APP_PAUSED", "ACCESS_EXPIRED", "ACCESS_DENIED", "IP_BLACKLISTED", "IP_NOT_WHITELISTED", "SID_BLACKLISTED", "SID_NOT_WHITELISTED", "VERSION_NOT_ALLOWED", "HASH_NOT_ALLOWED", "COUNTRY_BLOCKED", "VPN_NOT_ALLOWED", "DEVICE_NOT_ALLOWED", "INVALID_CREDENTIALS", "APP_DISABLED", "IP_BLOCKED", "SID_BLOCKED", "UPDATE_REQUIRED", "INVALID_HASH", "VPN_BLOCKED", "USER_BANNED", "USER_SUSPENDED", "USER_EXPIRED", "LICENSE_BANNED", "LICENSE_PAUSED", "LICENSE_EXPIRED", "MOTHERBOARD_BANNED", "MOTHERBOARD_PAUSED", "MOTHERBOARD_EXPIRED", "PROCESSOR_BANNED", "PROCESSOR_PAUSED", "PROCESSOR_EXPIRED", }: await self._invalidate(error) raise async def init(self): async with self._lock: return await self._request( "/v3/initialize", {"appKey": self.app_key, "version": self.version}, retry=True, ) async def login(self, username, password): return await self._login("user", username, password, "") async def registerUser(self, username, password, license_key): return await self._login("register", username, password, license_key) async def changePassword(self, current_password, new_password): async with self._lock: return await self._request( "/v3/account/password", {"currentPassword": current_password, "newPassword": new_password}, auth=True, ) async def redeemLicense(self, license_key): async with self._lock: return await self._request( "/v3/licenses/redeem", {"licenseKey": license_key}, auth=True ) async def log(self, message): async with self._lock: return await self._request("/v3/logs/add", {"message": message}, auth=True) async def licenseLogin(self, license_key): return await self._login("license", "", "", license_key) async def deviceLogin(self): return await self._login("device", "", "", "") async def _login(self, kind, username, password, license_key): async with self._lock: if self._token: raise AuthlyXError( "ALREADY_SIGNED_IN", "Sign out before starting another session.", "server", ) await self._clear_offline() self._logging_out = False challenge = ( await self._request( "/v3/challenge", {"appKey": self.app_key, "installationPublicKey": self._pem}, ) ).data operation = { "type": kind, "appKey": self.app_key, "version": self.version, "sid": self.sid, "hash": self.build_hash, "username": username, "password": password, "licenseKey": license_key, } signature = base64.b64encode( self._key.sign( compact( {"challenge": challenge["payload"], "operation": operation} ).encode() ) ).decode() result = await self._request( "/v3/login", { **operation, "challengeId": challenge["challengeId"], "signature": signature, }, ) i = result.data["identity"] self.userData = { **i, "Username": i.get("name") if i.get("type") == "user" else "", "LicenseKey": i.get("licenseKey") or (i.get("name") if i.get("type") == "license" else ""), "SID": i.get("systemId"), "Email": i.get("email"), "Plan": i.get("plan"), "ExpiryDate": i.get("expiry"), "Country": i.get("country"), "IpAddress": i.get("ipAddress"), "DeviceLimit": i.get("deviceLimit"), } self._app_id = json.loads(challenge["payload"])["appId"] self._identity_id, self._session_id, self._token = ( result.data["identityId"], result.data["sessionId"], result.data["token"], ) await self._lease(result.data) result.data = {k: v for k, v in result.data.items() if k != "token"} self._start_heartbeat() return result async def _lease(self, data): try: deadline = parse_time(data["accessDeadline"]) if not 0 < deadline <= self._now() + 7200100: raise ValueError() except (ValueError, TypeError, KeyError): error = AuthlyXError( "LEASE_INVALID", "The session deadline is invalid.", "security" ) await self._invalidate(error) raise error self._deadline = deadline for key in ("features", "featureValues", "metadata"): if key in data: self.userData[key] = data[key] self._heartbeat_seconds, self._jitter_seconds = max( 1, min(3600, data.get("heartbeatSeconds", 600)) ), max(0, min(15, data.get("jitterSeconds", 15))) async def checkSession(self): async with self._lock: result = await self._request("/v3/session/check", {}, True, True) await self._lease(result.data) return result async def _protected(self, path, data, retry): async with self._lock: if self._token and self._deadline <= self._now(): await self._lease( (await self._request("/v3/session/check", {}, True, True)).data ) return await self._request(path, data, True, retry) async def getMetadata(self, key=None): return await self._protected( "/v3/metadata/get", {"key": key} if key is not None else {}, True ) async def updateVariable(self, name, value): return await self._protected( "/v3/data/set", {"name": name, "value": value}, False ) async def getFeatures(self): return await self._protected("/v3/features/list", {}, True) async def getFeature(self, name): return await self._protected("/v3/features/get", {"name": name}, True) async def getAllMetadata(self): return await self._protected("/v3/metadata/list", {}, True) async def checkMetadata(self, key): return await self._protected("/v3/metadata/check", {"key": key}, True) async def sendWebhook(self, name, data): return await self._protected( "/v3/webhooks/send", {"event": name, "data": data}, False ) async def setMetadata(self, key, value): return await self._protected( "/v3/metadata/set", {"key": key, "value": value}, False ) async def checkFeature(self, name): return await self._protected("/v3/features/check", {"name": name}, True) async def getVariable(self, name): return await self._protected("/v3/data/get", {"name": name}, True) async def getScript(self, name, revision=None): result = await self._protected( "/v3/scripts/get", {"name": name, **({"revision": revision} if revision is not None else {})}, True, ) try: data = result.data manifest = json.loads(data["signedPayload"]) if "issuedAt" in manifest or "expiresAt" in manifest: issued, expires = manifest.get("issuedAt"), manifest.get("expiresAt") if ( type(issued) is not int or type(expires) is not int or issued > self._now() + 30000 or expires <= self._now() or expires <= issued ): raise ValueError() if "minimumRevision" in manifest and ( type(manifest["minimumRevision"]) is not int or manifest["revision"] < manifest["minimumRevision"] ): raise ValueError() key = serialization.load_pem_public_key( self.script_keys[manifest["keyId"]].encode() ) if not isinstance(key, Ed25519PublicKey): raise ValueError() key.verify( base64.b64decode(data["signature"], validate=True), data["signedPayload"].encode(), ) if ( data["manifest"] != manifest or manifest["appId"] != self._app_id or manifest["name"] != name or (revision is not None and revision != manifest["revision"]) or manifest["sha256"] != digest(data["content"]) or manifest["bytes"] != len(data["content"].encode()) ): raise ValueError() except Exception: raise AuthlyXError( "SCRIPT_INVALID", "The script could not be verified.", "security" ) from None return result async def saveOfflineAccess(self): async with self._lock: challenge = (await self._request("/v3/offline/challenge", {}, True)).data proof = { "challenge": challenge["payload"], "operation": {"action": "offlinePermit", "sessionId": self._session_id}, } result = await self._request( "/v3/offline/permit", { "challengeId": challenge["challengeId"], "signature": base64.b64encode( self._key.sign(compact(proof).encode()) ).decode(), }, True, ) self._offline = { "appId": self._app_id, "identityId": self._identity_id, "permit": result.data, "trustedTime": self._now(), "localTime": wall(), } if not self._valid_offline(): await self._clear_offline() raise AuthlyXError( "OFFLINE_INVALID", "The offline permit could not be verified.", "security", ) await self._persist() return result def _valid_offline(self): try: if ( self._offline is None or self._disposed or self._logging_out or wall() < self._wall ): return False permit = self._offline["permit"] if len(permit["signedPayload"]) > 4096: return False claims = json.loads(permit["signedPayload"]) key = serialization.load_pem_public_key( self.offline_keys[claims["keyId"]].encode() ) if not isinstance(key, Ed25519PublicKey) or key_id(key) != claims["keyId"]: return False key.verify( base64.b64decode(permit["signature"], validate=True), permit["signedPayload"].encode(), ) now = self._now() return ( claims["type"] == "authlyx.offline.v1" and claims["appId"] == self._app_id and claims["subjectId"] == self._identity_id and claims["installationKeyHash"] == self._installation_hash and claims["issuedAt"] <= now < claims["expiresAt"] and 0 < claims["expiresAt"] - claims["issuedAt"] <= 2592000000 and now >= self._offline["trustedTime"] ) except Exception: return False async def _persist(self): self._offline["trustedTime"], self._offline["localTime"] = self._now(), wall() await self.storage.save(self._prefix + ".offline", compact(self._offline)) async def hasOfflineAccess(self): async with self._lock: if not self._valid_offline(): return False try: await self._persist() return True except Exception: self._offline = None return False async def hasAccess(self): if self._disposed or self._logging_out: return False return ( bool(self._token and self._deadline > self._now()) or await self.hasOfflineAccess() ) async def logout(self): self._logging_out = True self._stop_heartbeat() async def cleanup(): async with self._lock: try: if self._token: await self._request("/v3/session/logout", {}, True) finally: self._stop_heartbeat() self._token, self._deadline = None, 0 self.userData = {} await self._clear_offline() task = asyncio.create_task(cleanup()) task.add_done_callback( lambda value: value.exception() if not value.cancelled() else None ) await asyncio.shield(task) def _stop_heartbeat(self): task, self._heartbeat = self._heartbeat, None if task and task is not asyncio.current_task(): task.cancel() def _start_heartbeat(self): self._stop_heartbeat() if not self.automatic or self._disposed or not self._token: return async def run(): try: while self._token and not self._disposed and not self._logging_out: await asyncio.sleep( max( 1, self._heartbeat_seconds + (secrets.randbelow(1000000) / 999999 * 2 - 1) * self._jitter_seconds, ) ) try: await self.checkSession() except AuthlyXError: pass except asyncio.CancelledError: pass self._heartbeat = asyncio.create_task(run()) async def onResume(self): return await self.checkSession() async def close(self): if self._disposed: return self._disposed = True self._stop_heartbeat() self._token, self._deadline = None, 0 self.userData = {} await self._http.close() self._state("disposed") async def __aenter__(self): return self async def __aexit__(self, *_): await self.close() ``` # Complete JavaScript / Node.js V3 SDK source ```javascript // AuthlyX JavaScript SDK Version 3.0 BETA import { createPrivateKey, createPublicKey, createHash, randomBytes, sign, verify, } from "node:crypto"; import { isDeepStrictEqual } from "node:util"; import { performance } from "node:perf_hooks"; import { setTimeout as sleep } from "node:timers/promises"; import { spawn, execFile, execFileSync } from "node:child_process"; import { readFile, writeFile, rename, mkdir, unlink } from "node:fs/promises"; import { join, resolve } from "node:path"; export class AuthlyX { runtime; get userData() { return this.runtime?.userData ?? {}; } closed = false; client; key; version; overrides; constructor(appKey, version, overrides = {}) { this.key = appKey; this.version = version; if ( overrides.heartbeat !== undefined && !["server", "manual"].includes(overrides.heartbeat) ) throw new Error("Use server or manual heartbeat mode."); this.overrides = { ...overrides, ...(overrides.api ? { endpoint: overrides.api } : {}), ...(overrides.requestTimeout !== undefined ? { requestBudgetMs: overrides.requestTimeout } : {}), ...(overrides.heartbeat !== undefined ? { automaticHeartbeat: overrides.heartbeat === "server" } : {}), }; } static systemId() { if (process.platform !== "win32") throw new Error("Supply a platform system ID through options."); const value = execFileSync( join(process.env.SystemRoot || "C:/Windows", "System32", "whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", windowsHide: true, timeout: 3000 }, ); const sid = value.match(/S-1-\d+(?:-\d+)+/); if (!sid) throw new Error("Could not read the Windows user SID."); return sid[0]; } static defaults(appKey, version, overrides = {}) { if (!overrides.storage && !process.env.LOCALAPPDATA) throw new Error("LOCALAPPDATA is unavailable."); return { appKey, version, systemId: overrides.systemId ?? AuthlyX.systemId(), endpoint: "https://api.authlyx.dev", allowLocalHttp: true, storage: overrides.storage ?? new WindowsProtectedStore(join(process.env.LOCALAPPDATA || "", "AuthlyX", "v3")), ...{ responseKeys: { "2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n", }, offlineKeys: { "d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n", }, scriptKeys: { "5aec455eb0b10697": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n", }, }, }; } ready() { if (this.closed) throw new AuthlyXError( "CLIENT_DISPOSED", "This AuthlyX instance is closed.", "cancelled", ); return (this.client ??= (async () => { let systemId = this.overrides.systemId; if (!systemId) { if (process.platform !== "win32") throw new Error("Supply a platform system ID through options."); const value = await new Promise((resolve, reject) => execFile( join(process.env.SystemRoot || "C:/Windows", "System32", "whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", windowsHide: true, timeout: 3000 }, (error, stdout) => (error ? reject(error) : resolve(stdout)), ), ); systemId = value.match(/S-1-\d+(?:-\d+)+/)?.[0]; if (!systemId) throw new Error("Could not read the Windows user SID."); } const runtime = await Runtime.create({ ...AuthlyX.defaults(this.key, this.version, { ...this.overrides, systemId, }), ...this.overrides, systemId, }); this.runtime = runtime; return runtime; })()); } deliver(operation, completed) { const success = operation.then((result) => ({ ...result, ok: result.success, failed: !result.success, })); if (!completed) return success; const settled = success.catch((error) => ({ success: false, ok: false, failed: true, code: error instanceof AuthlyXError ? error.code : "CLIENT_ERROR", message: error instanceof Error ? error.message : "The request failed.", data: null, requestId: error instanceof AuthlyXError ? error.requestId || "" : "", })); void settled.then(completed); return settled; } initialize(signalOrCallback) { return this.init(signalOrCallback); } init(signalOrCallback) { const callback = typeof signalOrCallback === "function" ? signalOrCallback : undefined; return this.deliver( (async () => (await this.ready()).init( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), callback, ); } login(usernameOrLicense, passwordOrCallback, signalOrCallback) { const callback = typeof passwordOrCallback === "function" ? passwordOrCallback : typeof signalOrCallback === "function" ? signalOrCallback : undefined; const signal = typeof signalOrCallback === "function" ? undefined : signalOrCallback; return this.deliver( (async () => { const app = await this.ready(); return typeof passwordOrCallback === "string" ? app.login(usernameOrLicense, passwordOrCallback, signal) : app.licenseLogin( usernameOrLicense, typeof passwordOrCallback === "function" ? signal : passwordOrCallback || signal, ); })(), callback, ); } registerUser(username, password, licenseKey, completed) { return this.deliver( (async () => (await this.ready()).registerUser(username, password, licenseKey))(), completed, ); } changePassword(currentPassword, newPassword, completed) { return this.deliver( (async () => (await this.ready()).changePassword(currentPassword, newPassword))(), completed, ); } redeemLicense(licenseKey, completed) { return this.deliver( (async () => (await this.ready()).redeemLicense(licenseKey))(), completed, ); } log(message, completed) { return this.deliver((async () => (await this.ready()).log(message))(), completed); } getVariable(name, completed) { return this.deliver( (async () => { const result = await (await this.ready()).getVariable(name); return { ...result, data: result.data.value }; })(), completed, ); } getScript(name, completed) { return this.deliver((async () => (await this.ready()).getScript(name))(), completed); } async deviceLogin(signal) { return (await this.ready()).deviceLogin(signal); } async checkSession(signal) { return (await this.ready()).checkSession(signal); } getMetadata(signalOrCallback) { const callback = typeof signalOrCallback === "function" ? signalOrCallback : undefined; return this.deliver( (async () => (await this.ready()).getMetadata( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), callback, ); } updateVariable(name, value, signalOrCallback) { return this.deliver( (async () => (await this.ready()).updateVariable( name, value, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getFeatures(signalOrCallback) { return this.deliver( (async () => (await this.ready()).getFeatures( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getFeature(name, signalOrCallback) { return this.deliver( (async () => (await this.ready()).getFeature( name, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getAllMetadata(signalOrCallback) { return this.deliver( (async () => (await this.ready()).getAllMetadata( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getMetadataValue(key, signalOrCallback) { return this.deliver( (async () => (await this.ready()).getMetadataValue( key, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } checkMetadata(key, signalOrCallback) { return this.deliver( (async () => (await this.ready()).checkMetadata( key, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } sendWebhook(eventName, data, signalOrCallback) { return this.deliver( (async () => (await this.ready()).sendWebhook( eventName, data, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } async setMetadata(key, value, signal) { return (await this.ready()).setMetadata(key, value, signal); } async checkFeature(name, signal) { return (await this.ready()).checkFeature(name, signal); } async saveOfflineAccess(signal) { return (await this.ready()).saveOfflineAccess(signal); } async hasAccess() { return (await this.ready()).hasAccess(); } async logout(signal) { return (await this.ready()).logout(signal); } async onResume(signal) { return (await this.ready()).onResume(signal); } async hasOfflineAccess() { return (await this.ready()).hasOfflineAccess(); } async close() { this.closed = true; const client = await this.client?.catch(() => undefined); client?.dispose(); } } export class MemoryStore { data = new Map(); async load(name) { return this.data.get(name) ?? null; } async save(name, value) { this.data.set(name, value); } async delete(name) { this.data.delete(name); } } const script = `$ErrorActionPreference='Stop';try{Add-Type -AssemblyName System.Security;$x=[Console]::In.ReadToEnd()|ConvertFrom-Json;$v=[Convert]::FromBase64String($x.value);$e=[Convert]::FromBase64String($x.entropy);if($x.mode -eq 'protect'){$o=[Security.Cryptography.ProtectedData]::Protect($v,$e,[Security.Cryptography.DataProtectionScope]::CurrentUser)}else{$o=[Security.Cryptography.ProtectedData]::Unprotect($v,$e,[Security.Cryptography.DataProtectionScope]::CurrentUser)};[Console]::Out.Write([Convert]::ToBase64String($o))}catch{exit 1}`; export class WindowsProtectedStore { directory; constructor(directory) { if (process.platform !== "win32") throw new Error( "WindowsProtectedStore requires Windows. Supply a platform-protected store.", ); this.directory = resolve(directory); } file(name) { return join(this.directory, createHash("sha256").update(name).digest("hex") + ".dat"); } crypt(name, value, mode) { return new Promise((ok, no) => { const child = spawn( "powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }, ); let output = ""; const timer = setTimeout(() => { child.kill(); no(new Error("Protected storage timed out.")); }, 10000); child.stdout.on("data", (chunk) => { output += chunk; if (output.length > 1500000) { child.kill(); no(new Error("Protected state is too large.")); } }); child.stderr.resume(); child.on("error", () => { clearTimeout(timer); no(new Error("Protected storage is unavailable.")); }); child.on("close", (code) => { clearTimeout(timer); code === 0 ? ok(Buffer.from(output, "base64")) : no(new Error("Protected state could not be read or saved.")); }); child.stdin.on("error", () => {}); child.stdin.end( JSON.stringify({ mode, value: value.toString("base64"), entropy: Buffer.from(name).toString("base64"), }), ); }); } async load(name) { let bytes; try { bytes = await readFile(this.file(name)); } catch (e) { if (e.code === "ENOENT") return null; throw e; } if (bytes.length > 1048576) throw new Error("Protected state is too large."); return (await this.crypt(name, bytes, "unprotect")).toString("utf8"); } async save(name, value) { await mkdir(this.directory, { recursive: true }); const file = this.file(name), temp = file + "." + randomBytes(8).toString("hex") + ".tmp"; try { await writeFile(temp, await this.crypt(name, Buffer.from(value), "protect"), { flag: "wx", mode: 0o600, }); await rename(temp, file); } finally { await unlink(temp).catch(() => {}); } } async delete(name) { await unlink(this.file(name)).catch((e) => { if (e.code !== "ENOENT") throw e; }); } } export class AuthlyXError extends Error { code; kind; status; requestId; constructor(code, message, kind, status = 0, requestId) { super(message); this.code = code; this.kind = kind; this.status = status; this.requestId = requestId; this.name = "AuthlyXError"; } } const hash = (value) => createHash("sha256").update(value).digest("hex"); const keyId = (key) => hash(key.export({ format: "der", type: "spki" })); const revoked = new Set([ "SESSION_EXPIRED", "ACCESS_REVOKED", "APP_PAUSED", "ACCESS_EXPIRED", "ACCESS_DENIED", "IP_BLACKLISTED", "IP_NOT_WHITELISTED", "SID_BLACKLISTED", "SID_NOT_WHITELISTED", "VERSION_NOT_ALLOWED", "HASH_NOT_ALLOWED", "COUNTRY_BLOCKED", "VPN_NOT_ALLOWED", "DEVICE_NOT_ALLOWED", "INVALID_CREDENTIALS", "APP_DISABLED", "IP_BLOCKED", "SID_BLOCKED", "UPDATE_REQUIRED", "INVALID_HASH", "VPN_BLOCKED", "USER_BANNED", "USER_SUSPENDED", "USER_EXPIRED", "LICENSE_BANNED", "LICENSE_PAUSED", "LICENSE_EXPIRED", "MOTHERBOARD_BANNED", "MOTHERBOARD_PAUSED", "MOTHERBOARD_EXPIRED", "PROCESSOR_BANNED", "PROCESSOR_PAUSED", "PROCESSOR_EXPIRED", ]); class Runtime { key; pem = ""; installationHash = ""; prefix = ""; identityName = ""; token; sessionId; appId; identityId; offline; anchorServer = 0; anchorMono = 0; anchorWall = 0; deadline = 0; tail = Promise.resolve(); controller = new AbortController(); timer; heartbeatSeconds = 600; jitterSeconds = 15; disposed = false; loggingOut = false; connection = "disconnected"; options; constructor(options) { if ( options.retryLimit !== undefined && (!Number.isInteger(options.retryLimit) || options.retryLimit < 0 || options.retryLimit > 5) ) throw new Error("Retry limit must be between zero and five."); this.options = { ...options, responseKeys: { ...options.responseKeys }, offlineKeys: { ...options.offlineKeys }, scriptKeys: { ...options.scriptKeys }, }; } static async create(options) { const url = new URL(options.endpoint); if ( url.pathname !== "/" || url.search || url.hash || url.username || url.password || (url.protocol !== "https:" && !( options.allowLocalHttp && url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) )) ) throw new Error( "Use an HTTPS API origin. HTTP is limited to explicit loopback testing.", ); if ( !options.appKey || !options.version || !options.systemId || !options.storage || !Object.keys(options.responseKeys).length ) throw new Error( "Provide AppKey, version, system ID, protected storage and trusted response keys.", ); if ((options.requestBudgetMs ?? 8000) < 100 || (options.requestBudgetMs ?? 8000) > 60000) throw new Error("Request budget must be 100 ms to 60 seconds."); const client = new Runtime({ ...options, endpoint: url.origin }); client.prefix = "authlyx.v3." + hash(url.href + "\n" + options.appKey + "\n" + options.systemId); client.identityName = "authlyx.v3.installation." + hash(url.href + "\n" + options.systemId); try { let saved = await options.storage.load(client.identityName); const seed = saved ? Buffer.from(saved, "base64") : randomBytes(32); if (seed.length !== 32) throw new Error(); if (!saved) await options.storage.save(client.identityName, seed.toString("base64")); client.key = createPrivateKey({ key: Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), seed]), format: "der", type: "pkcs8", }); seed.fill(0); const pub = createPublicKey(client.key); client.pem = pub.export({ format: "pem", type: "spki" }).toString(); client.installationHash = keyId(pub); saved = await options.storage.load(client.prefix + ".offline"); if (saved) { client.offline = JSON.parse(saved); const state = client.offline; if (Date.now() < state.localTime) throw new Error(); client.appId = state.appId; client.identityId = state.identityId; client.anchor(state.trustedTime + Date.now() - state.localTime); if (!client.validOffline()) await client.clearOffline(); } } catch { throw new AuthlyXError( "STORAGE_INVALID", "Protected SDK state could not be read or saved.", "storage", ); } return client; } anchor(value) { this.anchorServer = value; this.anchorMono = performance.now(); this.anchorWall = Date.now(); } now() { return this.anchorServer ? Math.floor(this.anchorServer + performance.now() - this.anchorMono) : Date.now(); } state(state) { if (this.connection === state) return; this.connection = state; try { this.options.onConnection?.(state); } catch {} } async clearOffline() { this.offline = undefined; await this.options.storage.delete(this.prefix + ".offline"); } async invalidate(error) { this.token = undefined; this.userData = {}; this.deadline = 0; this.stopHeartbeat(); try { await this.clearOffline(); } catch {} try { this.options.onSessionInvalidated?.(error); } catch {} } async queued(action, signal) { if (this.disposed) throw new AuthlyXError("DISPOSED", "This client is disposed.", "cancelled"); const result = this.tail .catch(() => {}) .then(async () => { if (signal?.aborted) throw new AuthlyXError( "REQUEST_CANCELLED", "The request was cancelled.", "cancelled", ); if (this.disposed) throw new AuthlyXError("DISPOSED", "This client is disposed.", "cancelled"); return action(); }); this.tail = result.catch(() => {}); return result; } verifyResponse(outer, status, path, body, nonce) { try { const proof = outer.verification, pem = this.options.responseKeys[proof.keyId]; if ( typeof proof.signedPayload !== "string" || proof.signedPayload.length > 2000000 || !pem || keyId(createPublicKey(pem)) !== proof.keyId || !verify( null, Buffer.from(proof.signedPayload), pem, Buffer.from(proof.signature, "base64"), ) ) throw new Error(); const signed = JSON.parse(proof.signedPayload), { verification, ...envelope } = outer; if ( signed.type !== "authlyx.response.v3" || signed.keyId !== proof.keyId || signed.httpStatus !== status || signed.request.method !== "POST" || signed.request.path !== path || signed.request.nonce !== nonce || signed.request.bodySha256 !== hash(body) || !isDeepStrictEqual(signed.response, envelope) || typeof envelope.message !== "string" || typeof envelope.success !== "boolean" || typeof envelope.code !== "string" || typeof envelope.requestId !== "string" || !Number.isFinite(Date.parse(signed.serverTime)) ) throw new Error(); this.anchor(Date.parse(signed.serverTime)); return signed.response; } catch { throw new AuthlyXError( "RESPONSE_INVALID", "The server response could not be verified.", "security", ); } } async request(path, data, authenticated, retryable, caller) { if (authenticated && !this.token) throw new AuthlyXError("NOT_SIGNED_IN", "Sign in before using this feature.", "server"); const body = JSON.stringify(data), budget = this.options.requestBudgetMs ?? 8000, start = performance.now(); const timeout = AbortSignal.timeout(budget), signal = AbortSignal.any([ timeout, this.controller.signal, ...(caller ? [caller] : []), ]); for (let attempt = 0; ; attempt++) { const nonce = randomBytes(24).toString("hex"), timestamp = String(Math.floor(this.now())); const headers = { "Content-Type": "application/json", "X-AuthlyX-Nonce": nonce, }; if (authenticated) { headers.Authorization = "Bearer " + this.token; headers["X-AuthlyX-Timestamp"] = timestamp; headers["X-AuthlyX-Signature"] = sign( null, Buffer.from( JSON.stringify({ type: "authlyx.request.v3", method: "POST", path, bodySha256: hash(body), nonce, timestamp, tokenHash: hash(this.token), }), ), this.key, ).toString("base64"); } try { const response = await fetch(this.options.endpoint + path, { method: "POST", headers, body, signal, redirect: "error", }); const reader = response.body?.getReader(); let length = 0; const chunks = []; if (reader) for (;;) { const next = await reader.read(); if (next.done) break; length += next.value.byteLength; if (length > 2000000) { await reader.cancel(); throw new AuthlyXError( "RESPONSE_INVALID", "The server response is too large.", "security", ); } chunks.push(next.value); } let outer; try { outer = JSON.parse(Buffer.concat(chunks).toString()); } catch { throw new AuthlyXError( response.status >= 500 ? "SERVICE_UNAVAILABLE" : "RESPONSE_INVALID", response.status >= 500 ? "The service is temporarily unavailable." : "The server response is not valid JSON.", response.status >= 500 ? "network" : "security", response.status, ); } if (!outer.verification && response.status >= 500) throw new AuthlyXError( "SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network", response.status, ); const value = this.verifyResponse(outer, response.status, path, body, nonce); this.state("online"); if (!response.ok || !value.success) { const kind = response.status === 429 || response.status >= 500 ? "network" : "server"; if ( retryable && attempt < (this.options.retryLimit ?? 2) && (kind === "network" || value.code === "REQUEST_TIME_INVALID") ) { const after = response.headers.get("retry-after"); let delay = after === null ? 150 * (attempt + 1) : /^\d+$/.test(after) ? Number(after) * 1000 : Date.parse(after) - Date.now(); if ( Number.isFinite(delay) && delay >= 0 && performance.now() - start + delay + 50 < budget ) { await sleep(delay, undefined, { signal }); continue; } } throw new AuthlyXError( value.code, value.message, kind, response.status, value.requestId, ); } return { ...value, ok: value.success, failed: !value.success }; } catch (error) { if (caller?.aborted || this.controller.signal.aborted) throw new AuthlyXError( "REQUEST_CANCELLED", "The request was cancelled.", "cancelled", ); let failure; if (error instanceof AuthlyXError) failure = error; else failure = new AuthlyXError( timeout.aborted ? "NETWORK_TIMEOUT" : "NETWORK_ERROR", timeout.aborted ? "The request timed out. Try again when connected." : "Could not connect to AuthlyX.", "network", ); if (failure.kind === "security") { this.state("untrusted"); await this.invalidate(failure); } else if (failure.kind === "network") { this.state("disconnected"); if ( !(error instanceof AuthlyXError) && retryable && attempt < (this.options.retryLimit ?? 2) && !timeout.aborted && performance.now() - start + 200 < budget ) { try { await sleep(150, undefined, { signal }); continue; } catch { throw failure; } } } else if (authenticated && revoked.has(failure.code)) await this.invalidate(failure); throw failure; } } } async init(signal) { return this.queued( () => this.request( "/v3/initialize", { appKey: this.options.appKey, version: this.options.version }, false, true, signal, ), signal, ); } login(username, password, signal) { return this.signIn("user", username, password, "", signal); } licenseLogin(licenseKey, signal) { return this.signIn("license", "", "", licenseKey, signal); } deviceLogin(signal) { return this.signIn("device", "", "", "", signal); } registerUser(username, password, licenseKey) { return this.signIn("register", username, password, licenseKey); } changePassword(currentPassword, newPassword) { return this.protected("/v3/account/password", { currentPassword, newPassword }, false); } redeemLicense(licenseKey) { return this.protected("/v3/licenses/redeem", { licenseKey }, false); } log(message) { return this.protected("/v3/logs/add", { message }, false); } userData = {}; signIn(type, username, password, licenseKey, signal) { return this.queued(async () => { if (this.token) throw new AuthlyXError( "ALREADY_SIGNED_IN", "Sign out before starting another session.", "server", ); await this.clearOffline(); this.loggingOut = false; const challenge = ( await this.request( "/v3/challenge", { appKey: this.options.appKey, installationPublicKey: this.pem }, false, false, signal, ) ).data; const operation = { type, appKey: this.options.appKey, version: this.options.version, sid: this.options.systemId, hash: this.options.buildHash ?? "", username, password, licenseKey, }; const signature = sign( null, Buffer.from(JSON.stringify({ challenge: challenge.payload, operation })), this.key, ).toString("base64"); const result = await this.request( "/v3/login", { ...operation, challengeId: challenge.challengeId, signature }, false, false, signal, ); this.appId = JSON.parse(challenge.payload).appId; this.identityId = result.data.identityId; this.userData = userDataFields(result.data.identity); this.sessionId = result.data.sessionId; this.token = result.data.token; await this.acceptLease(result.data); this.startHeartbeat(); const { token, ...data } = result.data; return { ...result, data }; }, signal); } async acceptLease(data) { const value = Date.parse(data.accessDeadline); if (!Number.isFinite(value) || value <= 0 || value > this.now() + 7200001) { const error = new AuthlyXError( "LEASE_INVALID", "The session deadline is invalid.", "security", ); await this.invalidate(error); throw error; } this.deadline = value; for (const key of ["features", "featureValues", "metadata"]) { if (Object.prototype.hasOwnProperty.call(data, key)) this.userData[key] = data[key]; } this.heartbeatSeconds = Math.max(1, Math.min(3600, data.heartbeatSeconds ?? 600)); this.jitterSeconds = Math.max(0, Math.min(15, data.jitterSeconds ?? 15)); } checkSession(signal) { return this.queued(async () => { const value = await this.request("/v3/session/check", {}, true, true, signal); await this.acceptLease(value.data); return value; }, signal); } protected(path, data, retryable, signal) { return this.queued(async () => { if (this.token && this.deadline <= this.now()) { const value = await this.request("/v3/session/check", {}, true, true, signal); await this.acceptLease(value.data); } return this.request(path, data, true, retryable, signal); }, signal); } getMetadata(signal) { return this.protected("/v3/metadata/get", {}, true, signal); } updateVariable(name, value, signal) { return this.protected("/v3/data/set", { name, value }, false, signal); } getFeatures(signal) { return this.protected("/v3/features/list", {}, true, signal); } getFeature(name, signal) { return this.protected("/v3/features/get", { name }, true, signal); } getAllMetadata(signal) { return this.protected("/v3/metadata/list", {}, true, signal); } getMetadataValue(key, signal) { return this.protected("/v3/metadata/get", { key }, true, signal); } checkMetadata(key, signal) { return this.protected("/v3/metadata/check", { key }, true, signal); } sendWebhook(eventName, data, signal) { return this.protected("/v3/webhooks/send", { event: eventName, data }, false, signal); } setMetadata(key, value, signal) { return this.protected("/v3/metadata/set", { key, value }, false, signal); } checkFeature(name, signal) { return this.protected("/v3/features/check", { name }, true, signal); } getVariable(name, signal) { return this.protected("/v3/data/get", { name }, true, signal); } async getScript(name, revision, signal) { const result = await this.protected( "/v3/scripts/get", { name, ...(revision !== undefined ? { revision } : {}) }, true, signal, ), data = result.data; try { const manifest = JSON.parse(data.signedPayload), pem = this.options.scriptKeys?.[manifest.keyId]; if (Object.hasOwn(manifest, "issuedAt") || Object.hasOwn(manifest, "expiresAt")) { if ( !Number.isSafeInteger(manifest.issuedAt) || !Number.isSafeInteger(manifest.expiresAt) || manifest.issuedAt > this.now() + 30000 || manifest.expiresAt <= this.now() || manifest.expiresAt <= manifest.issuedAt ) throw new Error(); } if ( Object.hasOwn(manifest, "minimumRevision") && (!Number.isSafeInteger(manifest.minimumRevision) || manifest.revision < manifest.minimumRevision) ) throw new Error(); if ( !pem || !verify( null, Buffer.from(data.signedPayload), pem, Buffer.from(data.signature, "base64"), ) || !isDeepStrictEqual(data.manifest, manifest) || manifest.appId !== this.appId || manifest.name !== name || (revision !== undefined && manifest.revision !== revision) || manifest.sha256 !== hash(data.content) || manifest.bytes !== Buffer.byteLength(data.content) ) throw new Error(); } catch { const error = new AuthlyXError( "SCRIPT_INVALID", "The script could not be verified.", "security", ); throw error; } return result; } saveOfflineAccess(signal) { return this.queued(async () => { const challenge = (await this.request("/v3/offline/challenge", {}, true, false, signal)) .data; const signature = sign( null, Buffer.from( JSON.stringify({ challenge: challenge.payload, operation: { action: "offlinePermit", sessionId: this.sessionId }, }), ), this.key, ).toString("base64"); const result = await this.request( "/v3/offline/permit", { challengeId: challenge.challengeId, signature }, true, false, signal, ); this.offline = { appId: this.appId, identityId: this.identityId, permit: result.data, trustedTime: this.now(), localTime: Date.now(), }; if (!this.validOffline()) { await this.clearOffline(); throw new AuthlyXError( "OFFLINE_INVALID", "The offline permit could not be verified.", "security", ); } await this.persistOffline(); return result; }, signal); } validOffline() { try { if (!this.offline || this.disposed || this.loggingOut || Date.now() < this.anchorWall) return false; const { signedPayload, signature } = this.offline.permit; if (signedPayload.length > 4096) return false; const claims = JSON.parse(signedPayload), pem = this.options.offlineKeys?.[claims.keyId], now = this.now(); return ( !!pem && keyId(createPublicKey(pem)) === claims.keyId && verify(null, Buffer.from(signedPayload), pem, Buffer.from(signature, "base64")) && claims.type === "authlyx.offline.v1" && claims.appId === this.appId && claims.subjectId === this.identityId && claims.installationKeyHash === this.installationHash && Number.isFinite(claims.issuedAt) && Number.isFinite(claims.expiresAt) && now >= claims.issuedAt && now < claims.expiresAt && claims.expiresAt > claims.issuedAt && claims.expiresAt - claims.issuedAt <= 2592000000 && now >= this.offline.trustedTime ); } catch { return false; } } async persistOffline() { if (this.offline) { this.offline.trustedTime = this.now(); this.offline.localTime = Date.now(); await this.options.storage.save(this.prefix + ".offline", JSON.stringify(this.offline)); } } async hasOfflineAccess() { return this.queued(async () => { if (!this.validOffline()) return false; try { await this.persistOffline(); return true; } catch { this.offline = undefined; return false; } }); } async hasAccess() { if (this.disposed || this.loggingOut) return false; if (this.token && this.deadline > this.now()) return true; return this.hasOfflineAccess(); } async logout(signal) { this.loggingOut = true; this.stopHeartbeat(); return this.queued(async () => { try { if (this.token) await this.request("/v3/session/logout", {}, true, false, signal); } finally { this.stopHeartbeat(); this.token = undefined; this.userData = {}; this.deadline = 0; await this.clearOffline(); } }); } stopHeartbeat() { if (this.timer) clearTimeout(this.timer); this.timer = undefined; } startHeartbeat() { this.stopHeartbeat(); if (this.options.automaticHeartbeat === false || this.disposed || !this.token) return; const delay = Math.max( 1, this.heartbeatSeconds + ((randomBytes(4).readUInt32LE() / 0xffffffff) * 2 - 1) * this.jitterSeconds, ) * 1000; this.timer = setTimeout(async () => { try { await this.checkSession(); } catch {} if (this.token && !this.disposed && !this.loggingOut) this.startHeartbeat(); }, delay); this.timer.unref(); } onResume(signal) { return this.checkSession(signal); } dispose() { if (this.disposed) return; this.disposed = true; this.stopHeartbeat(); this.controller.abort(); this.token = undefined; this.userData = {}; this.deadline = 0; this.state("disposed"); } } export { Runtime as Client }; function userDataFields(i) { return { ...i, Username: i.type === "user" ? i.name : "", LicenseKey: i.licenseKey || (i.type === "license" ? i.name : ""), SID: i.systemId, Email: i.email, Plan: i.plan, ExpiryDate: i.expiry, Country: i.country, IpAddress: i.ipAddress, DeviceLimit: i.deviceLimit, }; } ``` # Complete TypeScript V3 SDK source ```typescript // AuthlyX TypeScript SDK Version 3.0 BETA import { createPrivateKey, createPublicKey, createHash, randomBytes, sign, verify, type KeyObject, } from "node:crypto"; import { isDeepStrictEqual } from "node:util"; import { performance } from "node:perf_hooks"; import { setTimeout as sleep } from "node:timers/promises"; import { spawn, execFile, execFileSync } from "node:child_process"; import { readFile, writeFile, rename, mkdir, unlink } from "node:fs/promises"; import { join, resolve } from "node:path"; export class AuthlyX { private runtime?: Runtime; get userData() { return this.runtime?.userData ?? {}; } private closed = false; private client?: Promise; private readonly key: string; private readonly version: string; private readonly overrides: Partial; constructor(appKey: string, version: string, overrides: Partial = {}) { this.key = appKey; this.version = version; if ( overrides.heartbeat !== undefined && !["server", "manual"].includes(overrides.heartbeat) ) throw new Error("Use server or manual heartbeat mode."); this.overrides = { ...overrides, ...(overrides.api ? { endpoint: overrides.api } : {}), ...(overrides.requestTimeout !== undefined ? { requestBudgetMs: overrides.requestTimeout } : {}), ...(overrides.heartbeat !== undefined ? { automaticHeartbeat: overrides.heartbeat === "server" } : {}), }; } static systemId(): string { if (process.platform !== "win32") throw new Error("Supply a platform system ID through options."); const value = execFileSync( join(process.env.SystemRoot || "C:/Windows", "System32", "whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", windowsHide: true, timeout: 3000 }, ); const sid = value.match(/S-1-\d+(?:-\d+)+/); if (!sid) throw new Error("Could not read the Windows user SID."); return sid[0]; } static defaults(appKey: string, version: string, overrides: Partial = {}): Options { if (!overrides.storage && !process.env.LOCALAPPDATA) throw new Error("LOCALAPPDATA is unavailable."); return { appKey, version, systemId: overrides.systemId ?? AuthlyX.systemId(), endpoint: "https://api.authlyx.dev", allowLocalHttp: true, storage: overrides.storage ?? new WindowsProtectedStore(join(process.env.LOCALAPPDATA || "", "AuthlyX", "v3")), ...{ responseKeys: { "2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n", }, offlineKeys: { "d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n", }, scriptKeys: { "5aec455eb0b10697": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n", }, }, }; } private ready(): Promise { if (this.closed) throw new AuthlyXError( "CLIENT_DISPOSED", "This AuthlyX instance is closed.", "cancelled", ); return (this.client ??= (async () => { let systemId = this.overrides.systemId; if (!systemId) { if (process.platform !== "win32") throw new Error("Supply a platform system ID through options."); const value = await new Promise((resolve, reject) => execFile( join(process.env.SystemRoot || "C:/Windows", "System32", "whoami.exe"), ["/user", "/fo", "csv", "/nh"], { encoding: "utf8", windowsHide: true, timeout: 3000 }, (error, stdout) => (error ? reject(error) : resolve(stdout)), ), ); systemId = value.match(/S-1-\d+(?:-\d+)+/)?.[0]; if (!systemId) throw new Error("Could not read the Windows user SID."); } const runtime: Runtime = await Runtime.create({ ...AuthlyX.defaults(this.key, this.version, { ...this.overrides, systemId, }), ...this.overrides, systemId, }); this.runtime = runtime; return runtime; })()); } private deliver( operation: Promise>, completed?: (result: Result) => void, ): Promise> { const success = operation.then((result) => ({ ...result, ok: result.success, failed: !result.success, })); if (!completed) return success; const settled = success.catch((error) => ({ success: false, ok: false, failed: true, code: error instanceof AuthlyXError ? error.code : "CLIENT_ERROR", message: error instanceof Error ? error.message : "The request failed.", data: null as T, requestId: error instanceof AuthlyXError ? error.requestId || "" : "", })); void settled.then(completed); return settled; } initialize( signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.init(signalOrCallback); } init(signalOrCallback?: AbortSignal | ((result: Result>) => void)) { const callback = typeof signalOrCallback === "function" ? signalOrCallback : undefined; return this.deliver( (async () => (await this.ready()).init( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), callback, ); } login( usernameOrLicense: string, passwordOrCallback?: string | AbortSignal | ((result: Result) => void), signalOrCallback?: AbortSignal | ((result: Result) => void), ) { const callback = typeof passwordOrCallback === "function" ? passwordOrCallback : typeof signalOrCallback === "function" ? signalOrCallback : undefined; const signal = typeof signalOrCallback === "function" ? undefined : signalOrCallback; return this.deliver( (async () => { const app = await this.ready(); return typeof passwordOrCallback === "string" ? app.login(usernameOrLicense, passwordOrCallback, signal) : app.licenseLogin( usernameOrLicense, typeof passwordOrCallback === "function" ? signal : passwordOrCallback || signal, ); })(), callback, ); } registerUser( username: string, password: string, licenseKey: string, completed?: (result: Result) => void, ) { return this.deliver( (async () => (await this.ready()).registerUser(username, password, licenseKey))(), completed, ); } changePassword( currentPassword: string, newPassword: string, completed?: (result: Result) => void, ) { return this.deliver( (async () => (await this.ready()).changePassword(currentPassword, newPassword))(), completed, ); } redeemLicense(licenseKey: string, completed?: (result: Result) => void) { return this.deliver( (async () => (await this.ready()).redeemLicense(licenseKey))(), completed, ); } log(message: string, completed?: (result: Result) => void) { return this.deliver((async () => (await this.ready()).log(message))(), completed); } getVariable(name: string, completed?: (result: Result) => void) { return this.deliver( (async () => { const result = await (await this.ready()).getVariable(name); return { ...result, data: result.data.value }; })(), completed, ); } getScript(name: string, completed?: (result: Result) => void) { return this.deliver((async () => (await this.ready()).getScript(name))(), completed); } async deviceLogin(signal?: AbortSignal) { return (await this.ready()).deviceLogin(signal); } async checkSession(signal?: AbortSignal) { return (await this.ready()).checkSession(signal); } getMetadata( signalOrCallback?: | AbortSignal | (( result: Result<{ features: string[]; metadata: Record; }>, ) => void), ) { const callback = typeof signalOrCallback === "function" ? signalOrCallback : undefined; return this.deliver( (async () => (await this.ready()).getMetadata( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), callback, ); } updateVariable( name: string, value: string, signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.deliver( (async () => (await this.ready()).updateVariable( name, value, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getFeatures( signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.deliver( (async () => (await this.ready()).getFeatures( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getFeature( name: string, signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.deliver( (async () => (await this.ready()).getFeature( name, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getAllMetadata( signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.deliver( (async () => (await this.ready()).getAllMetadata( typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } getMetadataValue( key: string, signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.deliver( (async () => (await this.ready()).getMetadataValue( key, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } checkMetadata( key: string, signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.deliver( (async () => (await this.ready()).checkMetadata( key, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } sendWebhook( eventName: string, data: unknown, signalOrCallback?: AbortSignal | ((result: Result>) => void), ) { return this.deliver( (async () => (await this.ready()).sendWebhook( eventName, data, typeof signalOrCallback === "function" ? undefined : signalOrCallback, ))(), typeof signalOrCallback === "function" ? signalOrCallback : undefined, ); } async setMetadata(key: string, value: string | number | boolean | null, signal?: AbortSignal) { return (await this.ready()).setMetadata(key, value, signal); } async checkFeature(name: string, signal?: AbortSignal) { return (await this.ready()).checkFeature(name, signal); } async saveOfflineAccess(signal?: AbortSignal) { return (await this.ready()).saveOfflineAccess(signal); } async hasAccess() { return (await this.ready()).hasAccess(); } async logout(signal?: AbortSignal) { return (await this.ready()).logout(signal); } async onResume(signal?: AbortSignal) { return (await this.ready()).onResume(signal); } async hasOfflineAccess() { return (await this.ready()).hasOfflineAccess(); } async close() { this.closed = true; const client = await this.client?.catch(() => undefined); client?.dispose(); } } export interface ProtectedStore { load(name: string): Promise; save(name: string, value: string): Promise; delete(name: string): Promise; } export class MemoryStore implements ProtectedStore { private data = new Map(); async load(name: string) { return this.data.get(name) ?? null; } async save(name: string, value: string) { this.data.set(name, value); } async delete(name: string) { this.data.delete(name); } } const script = `$ErrorActionPreference='Stop';try{Add-Type -AssemblyName System.Security;$x=[Console]::In.ReadToEnd()|ConvertFrom-Json;$v=[Convert]::FromBase64String($x.value);$e=[Convert]::FromBase64String($x.entropy);if($x.mode -eq 'protect'){$o=[Security.Cryptography.ProtectedData]::Protect($v,$e,[Security.Cryptography.DataProtectionScope]::CurrentUser)}else{$o=[Security.Cryptography.ProtectedData]::Unprotect($v,$e,[Security.Cryptography.DataProtectionScope]::CurrentUser)};[Console]::Out.Write([Convert]::ToBase64String($o))}catch{exit 1}`; export class WindowsProtectedStore implements ProtectedStore { private directory: string; constructor(directory: string) { if (process.platform !== "win32") throw new Error( "WindowsProtectedStore requires Windows. Supply a platform-protected store.", ); this.directory = resolve(directory); } private file(name: string) { return join(this.directory, createHash("sha256").update(name).digest("hex") + ".dat"); } private crypt(name: string, value: Buffer, mode: string): Promise { return new Promise((ok, no) => { const child = spawn( "powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }, ); let output = ""; const timer = setTimeout(() => { child.kill(); no(new Error("Protected storage timed out.")); }, 10000); child.stdout.on("data", (chunk) => { output += chunk; if (output.length > 1500000) { child.kill(); no(new Error("Protected state is too large.")); } }); child.stderr.resume(); child.on("error", () => { clearTimeout(timer); no(new Error("Protected storage is unavailable.")); }); child.on("close", (code) => { clearTimeout(timer); code === 0 ? ok(Buffer.from(output, "base64")) : no(new Error("Protected state could not be read or saved.")); }); child.stdin.on("error", () => {}); child.stdin.end( JSON.stringify({ mode, value: value.toString("base64"), entropy: Buffer.from(name).toString("base64"), }), ); }); } async load(name: string) { let bytes: Buffer; try { bytes = await readFile(this.file(name)); } catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return null; throw e; } if (bytes.length > 1048576) throw new Error("Protected state is too large."); return (await this.crypt(name, bytes, "unprotect")).toString("utf8"); } async save(name: string, value: string) { await mkdir(this.directory, { recursive: true }); const file = this.file(name), temp = file + "." + randomBytes(8).toString("hex") + ".tmp"; try { await writeFile(temp, await this.crypt(name, Buffer.from(value), "protect"), { flag: "wx", mode: 0o600, }); await rename(temp, file); } finally { await unlink(temp).catch(() => {}); } } async delete(name: string) { await unlink(this.file(name)).catch((e) => { if (e.code !== "ENOENT") throw e; }); } } export type FailureKind = "server" | "network" | "security" | "cancelled" | "storage"; export class AuthlyXError extends Error { constructor( public code: string, message: string, public kind: FailureKind, public status = 0, public requestId?: string, ) { super(message); this.name = "AuthlyXError"; } } export type Result = { success: boolean; readonly ok?: boolean; readonly failed?: boolean; code: string; message: string; data: T; requestId: string; }; export type ConnectionState = "online" | "disconnected" | "untrusted" | "disposed"; export type Session = { identity: Record; sessionId: string; identityId: string; application: string; expiresAt: string; accessDeadline: string; }; export interface Options { appKey: string; version: string; systemId: string; endpoint: string; responseKeys: Record; offlineKeys?: Record; scriptKeys?: Record; storage: ProtectedStore; buildHash?: string; requestBudgetMs?: number; automaticHeartbeat?: boolean; heartbeat?: "server" | "manual"; api?: string; debug?: boolean; requestTimeout?: number; retryLimit?: number; allowLocalHttp?: boolean; onConnection?: (state: ConnectionState) => void; onSessionInvalidated?: (error: AuthlyXError) => void; } const hash = (value: string | Buffer) => createHash("sha256").update(value).digest("hex"); const keyId = (key: KeyObject) => hash(key.export({ format: "der", type: "spki" }) as Buffer); const revoked = new Set([ "SESSION_EXPIRED", "ACCESS_REVOKED", "APP_PAUSED", "ACCESS_EXPIRED", "ACCESS_DENIED", "IP_BLACKLISTED", "IP_NOT_WHITELISTED", "SID_BLACKLISTED", "SID_NOT_WHITELISTED", "VERSION_NOT_ALLOWED", "HASH_NOT_ALLOWED", "COUNTRY_BLOCKED", "VPN_NOT_ALLOWED", "DEVICE_NOT_ALLOWED", "INVALID_CREDENTIALS", "APP_DISABLED", "IP_BLOCKED", "SID_BLOCKED", "UPDATE_REQUIRED", "INVALID_HASH", "VPN_BLOCKED", "USER_BANNED", "USER_SUSPENDED", "USER_EXPIRED", "LICENSE_BANNED", "LICENSE_PAUSED", "LICENSE_EXPIRED", "MOTHERBOARD_BANNED", "MOTHERBOARD_PAUSED", "MOTHERBOARD_EXPIRED", "PROCESSOR_BANNED", "PROCESSOR_PAUSED", "PROCESSOR_EXPIRED", ]); type Permit = { signedPayload: string; signature: string }; type Offline = { appId: string; identityId: string; permit: Permit; trustedTime: number; localTime: number; }; class Runtime { private key!: KeyObject; private pem = ""; private installationHash = ""; private prefix = ""; private identityName = ""; private token?: string; private sessionId?: string; private appId?: string; private identityId?: string; private offline?: Offline; private anchorServer = 0; private anchorMono = 0; private anchorWall = 0; private deadline = 0; private tail: Promise = Promise.resolve(); private controller = new AbortController(); private timer?: NodeJS.Timeout; private heartbeatSeconds = 600; private jitterSeconds = 15; private disposed = false; private loggingOut = false; connection: ConnectionState = "disconnected"; private readonly options: Options; private constructor(options: Options) { if ( options.retryLimit !== undefined && (!Number.isInteger(options.retryLimit) || options.retryLimit < 0 || options.retryLimit > 5) ) throw new Error("Retry limit must be between zero and five."); this.options = { ...options, responseKeys: { ...options.responseKeys }, offlineKeys: { ...options.offlineKeys }, scriptKeys: { ...options.scriptKeys }, }; } static async create(options: Options): Promise { const url = new URL(options.endpoint); if ( url.pathname !== "/" || url.search || url.hash || url.username || url.password || (url.protocol !== "https:" && !( options.allowLocalHttp && url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) )) ) throw new Error( "Use an HTTPS API origin. HTTP is limited to explicit loopback testing.", ); if ( !options.appKey || !options.version || !options.systemId || !options.storage || !Object.keys(options.responseKeys).length ) throw new Error( "Provide AppKey, version, system ID, protected storage and trusted response keys.", ); if ((options.requestBudgetMs ?? 8000) < 100 || (options.requestBudgetMs ?? 8000) > 60000) throw new Error("Request budget must be 100 ms to 60 seconds."); const client = new Runtime({ ...options, endpoint: url.origin }); client.prefix = "authlyx.v3." + hash(url.href + "\n" + options.appKey + "\n" + options.systemId); client.identityName = "authlyx.v3.installation." + hash(url.href + "\n" + options.systemId); try { let saved = await options.storage.load(client.identityName); const seed = saved ? Buffer.from(saved, "base64") : randomBytes(32); if (seed.length !== 32) throw new Error(); if (!saved) await options.storage.save(client.identityName, seed.toString("base64")); client.key = createPrivateKey({ key: Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), seed]), format: "der", type: "pkcs8", }); seed.fill(0); const pub = createPublicKey(client.key); client.pem = pub.export({ format: "pem", type: "spki" }).toString(); client.installationHash = keyId(pub); saved = await options.storage.load(client.prefix + ".offline"); if (saved) { client.offline = JSON.parse(saved); const state = client.offline!; if (Date.now() < state.localTime) throw new Error(); client.appId = state.appId; client.identityId = state.identityId; client.anchor(state.trustedTime + Date.now() - state.localTime); if (!client.validOffline()) await client.clearOffline(); } } catch { throw new AuthlyXError( "STORAGE_INVALID", "Protected SDK state could not be read or saved.", "storage", ); } return client; } private anchor(value: number) { this.anchorServer = value; this.anchorMono = performance.now(); this.anchorWall = Date.now(); } private now() { return this.anchorServer ? Math.floor(this.anchorServer + performance.now() - this.anchorMono) : Date.now(); } private state(state: ConnectionState) { if (this.connection === state) return; this.connection = state; try { this.options.onConnection?.(state); } catch {} } private async clearOffline() { this.offline = undefined; await this.options.storage.delete(this.prefix + ".offline"); } private async invalidate(error: AuthlyXError) { this.token = undefined; this.userData = {}; this.deadline = 0; this.stopHeartbeat(); try { await this.clearOffline(); } catch {} try { this.options.onSessionInvalidated?.(error); } catch {} } private async queued(action: () => Promise, signal?: AbortSignal): Promise { if (this.disposed) throw new AuthlyXError("DISPOSED", "This client is disposed.", "cancelled"); const result = this.tail .catch(() => {}) .then(async () => { if (signal?.aborted) throw new AuthlyXError( "REQUEST_CANCELLED", "The request was cancelled.", "cancelled", ); if (this.disposed) throw new AuthlyXError("DISPOSED", "This client is disposed.", "cancelled"); return action(); }); this.tail = result.catch(() => {}); return result; } private verifyResponse(outer: any, status: number, path: string, body: string, nonce: string) { try { const proof = outer.verification, pem = this.options.responseKeys[proof.keyId]; if ( typeof proof.signedPayload !== "string" || proof.signedPayload.length > 2000000 || !pem || keyId(createPublicKey(pem)) !== proof.keyId || !verify( null, Buffer.from(proof.signedPayload), pem, Buffer.from(proof.signature, "base64"), ) ) throw new Error(); const signed = JSON.parse(proof.signedPayload), { verification, ...envelope } = outer; if ( signed.type !== "authlyx.response.v3" || signed.keyId !== proof.keyId || signed.httpStatus !== status || signed.request.method !== "POST" || signed.request.path !== path || signed.request.nonce !== nonce || signed.request.bodySha256 !== hash(body) || !isDeepStrictEqual(signed.response, envelope) || typeof envelope.message !== "string" || typeof envelope.success !== "boolean" || typeof envelope.code !== "string" || typeof envelope.requestId !== "string" || !Number.isFinite(Date.parse(signed.serverTime)) ) throw new Error(); this.anchor(Date.parse(signed.serverTime)); return signed.response; } catch { throw new AuthlyXError( "RESPONSE_INVALID", "The server response could not be verified.", "security", ); } } private async request( path: string, data: unknown, authenticated: boolean, retryable: boolean, caller?: AbortSignal, ): Promise> { if (authenticated && !this.token) throw new AuthlyXError("NOT_SIGNED_IN", "Sign in before using this feature.", "server"); const body = JSON.stringify(data), budget = this.options.requestBudgetMs ?? 8000, start = performance.now(); const timeout = AbortSignal.timeout(budget), signal = AbortSignal.any([ timeout, this.controller.signal, ...(caller ? [caller] : []), ]); for (let attempt = 0; ; attempt++) { const nonce = randomBytes(24).toString("hex"), timestamp = String(Math.floor(this.now())); const headers: Record = { "Content-Type": "application/json", "X-AuthlyX-Nonce": nonce, }; if (authenticated) { headers.Authorization = "Bearer " + this.token; headers["X-AuthlyX-Timestamp"] = timestamp; headers["X-AuthlyX-Signature"] = sign( null, Buffer.from( JSON.stringify({ type: "authlyx.request.v3", method: "POST", path, bodySha256: hash(body), nonce, timestamp, tokenHash: hash(this.token!), }), ), this.key, ).toString("base64"); } try { const response = await fetch(this.options.endpoint + path, { method: "POST", headers, body, signal, redirect: "error", }); const reader = response.body?.getReader(); let length = 0; const chunks: Uint8Array[] = []; if (reader) for (;;) { const next = await reader.read(); if (next.done) break; length += next.value.byteLength; if (length > 2000000) { await reader.cancel(); throw new AuthlyXError( "RESPONSE_INVALID", "The server response is too large.", "security", ); } chunks.push(next.value); } let outer; try { outer = JSON.parse(Buffer.concat(chunks).toString()); } catch { throw new AuthlyXError( response.status >= 500 ? "SERVICE_UNAVAILABLE" : "RESPONSE_INVALID", response.status >= 500 ? "The service is temporarily unavailable." : "The server response is not valid JSON.", response.status >= 500 ? "network" : "security", response.status, ); } if (!outer.verification && response.status >= 500) throw new AuthlyXError( "SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network", response.status, ); const value = this.verifyResponse(outer, response.status, path, body, nonce); this.state("online"); if (!response.ok || !value.success) { const kind = response.status === 429 || response.status >= 500 ? "network" : "server"; if ( retryable && attempt < (this.options.retryLimit ?? 2) && (kind === "network" || value.code === "REQUEST_TIME_INVALID") ) { const after = response.headers.get("retry-after"); let delay = after === null ? 150 * (attempt + 1) : /^\d+$/.test(after) ? Number(after) * 1000 : Date.parse(after) - Date.now(); if ( Number.isFinite(delay) && delay >= 0 && performance.now() - start + delay + 50 < budget ) { await sleep(delay, undefined, { signal }); continue; } } throw new AuthlyXError( value.code, value.message, kind, response.status, value.requestId, ); } return { ...value, ok: value.success, failed: !value.success }; } catch (error) { if (caller?.aborted || this.controller.signal.aborted) throw new AuthlyXError( "REQUEST_CANCELLED", "The request was cancelled.", "cancelled", ); let failure: AuthlyXError; if (error instanceof AuthlyXError) failure = error; else failure = new AuthlyXError( timeout.aborted ? "NETWORK_TIMEOUT" : "NETWORK_ERROR", timeout.aborted ? "The request timed out. Try again when connected." : "Could not connect to AuthlyX.", "network", ); if (failure.kind === "security") { this.state("untrusted"); await this.invalidate(failure); } else if (failure.kind === "network") { this.state("disconnected"); if ( !(error instanceof AuthlyXError) && retryable && attempt < (this.options.retryLimit ?? 2) && !timeout.aborted && performance.now() - start + 200 < budget ) { try { await sleep(150, undefined, { signal }); continue; } catch { throw failure; } } } else if (authenticated && revoked.has(failure.code)) await this.invalidate(failure); throw failure; } } } async init(signal?: AbortSignal) { return this.queued( () => this.request<{ initialized: boolean; application: string; currentVersion: string; }>( "/v3/initialize", { appKey: this.options.appKey, version: this.options.version }, false, true, signal, ), signal, ); } login(username: string, password: string, signal?: AbortSignal) { return this.signIn("user", username, password, "", signal); } licenseLogin(licenseKey: string, signal?: AbortSignal) { return this.signIn("license", "", "", licenseKey, signal); } deviceLogin(signal?: AbortSignal) { return this.signIn("device", "", "", "", signal); } registerUser(username: string, password: string, licenseKey: string) { return this.signIn("register", username, password, licenseKey); } changePassword(currentPassword: string, newPassword: string) { return this.protected>( "/v3/account/password", { currentPassword, newPassword }, false, ); } redeemLicense(licenseKey: string) { return this.protected>( "/v3/licenses/redeem", { licenseKey }, false, ); } log(message: string) { return this.protected>("/v3/logs/add", { message }, false); } userData: Record = {}; private signIn( type: string, username: string, password: string, licenseKey: string, signal?: AbortSignal, ) { return this.queued(async () => { if (this.token) throw new AuthlyXError( "ALREADY_SIGNED_IN", "Sign out before starting another session.", "server", ); await this.clearOffline(); this.loggingOut = false; const challenge = ( await this.request( "/v3/challenge", { appKey: this.options.appKey, installationPublicKey: this.pem }, false, false, signal, ) ).data; const operation = { type, appKey: this.options.appKey, version: this.options.version, sid: this.options.systemId, hash: this.options.buildHash ?? "", username, password, licenseKey, }; const signature = sign( null, Buffer.from(JSON.stringify({ challenge: challenge.payload, operation })), this.key, ).toString("base64"); const result = await this.request< Session & { token: string; heartbeatSeconds: number; jitterSeconds: number; } >( "/v3/login", { ...operation, challengeId: challenge.challengeId, signature }, false, false, signal, ); this.appId = JSON.parse(challenge.payload).appId; this.identityId = result.data.identityId; this.userData = userDataFields(result.data.identity); this.sessionId = result.data.sessionId; this.token = result.data.token; await this.acceptLease(result.data); this.startHeartbeat(); const { token, ...data } = result.data; return { ...result, data } as Result; }, signal); } private async acceptLease(data: any) { const value = Date.parse(data.accessDeadline); if (!Number.isFinite(value) || value <= 0 || value > this.now() + 7200001) { const error = new AuthlyXError( "LEASE_INVALID", "The session deadline is invalid.", "security", ); await this.invalidate(error); throw error; } this.deadline = value; for (const key of ["features", "featureValues", "metadata"]) { if (Object.prototype.hasOwnProperty.call(data, key)) this.userData[key] = data[key]; } this.heartbeatSeconds = Math.max(1, Math.min(3600, data.heartbeatSeconds ?? 600)); this.jitterSeconds = Math.max(0, Math.min(15, data.jitterSeconds ?? 15)); } checkSession(signal?: AbortSignal) { return this.queued(async () => { const value = await this.request("/v3/session/check", {}, true, true, signal); await this.acceptLease(value.data); return value; }, signal); } private protected(path: string, data: unknown, retryable: boolean, signal?: AbortSignal) { return this.queued(async () => { if (this.token && this.deadline <= this.now()) { const value = await this.request("/v3/session/check", {}, true, true, signal); await this.acceptLease(value.data); } return this.request(path, data, true, retryable, signal); }, signal); } getMetadata(signal?: AbortSignal) { return this.protected<{ features: string[]; metadata: Record; }>("/v3/metadata/get", {}, true, signal); } updateVariable(name: string, value: string, signal?: AbortSignal) { return this.protected>( "/v3/data/set", { name, value }, false, signal, ); } getFeatures(signal?: AbortSignal) { return this.protected>("/v3/features/list", {}, true, signal); } getFeature(name: string, signal?: AbortSignal) { return this.protected>("/v3/features/get", { name }, true, signal); } getAllMetadata(signal?: AbortSignal) { return this.protected>("/v3/metadata/list", {}, true, signal); } getMetadataValue(key: string, signal?: AbortSignal) { return this.protected>("/v3/metadata/get", { key }, true, signal); } checkMetadata(key: string, signal?: AbortSignal) { return this.protected>("/v3/metadata/check", { key }, true, signal); } sendWebhook(eventName: string, data: unknown, signal?: AbortSignal) { return this.protected>( "/v3/webhooks/send", { event: eventName, data }, false, signal, ); } setMetadata(key: string, value: string | number | boolean | null, signal?: AbortSignal) { return this.protected<{ features: string[]; metadata: Record; }>("/v3/metadata/set", { key, value }, false, signal); } checkFeature(name: string, signal?: AbortSignal) { return this.protected<{ name: string; enabled: boolean }>( "/v3/features/check", { name }, true, signal, ); } getVariable(name: string, signal?: AbortSignal) { return this.protected<{ name: string; value: string }>( "/v3/data/get", { name }, true, signal, ); } async getScript(name: string, revision?: number, signal?: AbortSignal) { const result = await this.protected( "/v3/scripts/get", { name, ...(revision !== undefined ? { revision } : {}) }, true, signal, ), data = result.data; try { const manifest = JSON.parse(data.signedPayload), pem = this.options.scriptKeys?.[manifest.keyId]; if (Object.hasOwn(manifest, "issuedAt") || Object.hasOwn(manifest, "expiresAt")) { if ( !Number.isSafeInteger(manifest.issuedAt) || !Number.isSafeInteger(manifest.expiresAt) || manifest.issuedAt > this.now() + 30000 || manifest.expiresAt <= this.now() || manifest.expiresAt <= manifest.issuedAt ) throw new Error(); } if ( Object.hasOwn(manifest, "minimumRevision") && (!Number.isSafeInteger(manifest.minimumRevision) || manifest.revision < manifest.minimumRevision) ) throw new Error(); if ( !pem || !verify( null, Buffer.from(data.signedPayload), pem, Buffer.from(data.signature, "base64"), ) || !isDeepStrictEqual(data.manifest, manifest) || manifest.appId !== this.appId || manifest.name !== name || (revision !== undefined && manifest.revision !== revision) || manifest.sha256 !== hash(data.content) || manifest.bytes !== Buffer.byteLength(data.content) ) throw new Error(); } catch { const error = new AuthlyXError( "SCRIPT_INVALID", "The script could not be verified.", "security", ); throw error; } return result; } saveOfflineAccess(signal?: AbortSignal) { return this.queued(async () => { const challenge = ( await this.request("/v3/offline/challenge", {}, true, false, signal) ).data; const signature = sign( null, Buffer.from( JSON.stringify({ challenge: challenge.payload, operation: { action: "offlinePermit", sessionId: this.sessionId }, }), ), this.key, ).toString("base64"); const result = await this.request( "/v3/offline/permit", { challengeId: challenge.challengeId, signature }, true, false, signal, ); this.offline = { appId: this.appId!, identityId: this.identityId!, permit: result.data, trustedTime: this.now(), localTime: Date.now(), }; if (!this.validOffline()) { await this.clearOffline(); throw new AuthlyXError( "OFFLINE_INVALID", "The offline permit could not be verified.", "security", ); } await this.persistOffline(); return result; }, signal); } private validOffline() { try { if (!this.offline || this.disposed || this.loggingOut || Date.now() < this.anchorWall) return false; const { signedPayload, signature } = this.offline.permit; if (signedPayload.length > 4096) return false; const claims = JSON.parse(signedPayload), pem = this.options.offlineKeys?.[claims.keyId], now = this.now(); return ( !!pem && keyId(createPublicKey(pem)) === claims.keyId && verify(null, Buffer.from(signedPayload), pem, Buffer.from(signature, "base64")) && claims.type === "authlyx.offline.v1" && claims.appId === this.appId && claims.subjectId === this.identityId && claims.installationKeyHash === this.installationHash && Number.isFinite(claims.issuedAt) && Number.isFinite(claims.expiresAt) && now >= claims.issuedAt && now < claims.expiresAt && claims.expiresAt > claims.issuedAt && claims.expiresAt - claims.issuedAt <= 2592000000 && now >= this.offline.trustedTime ); } catch { return false; } } private async persistOffline() { if (this.offline) { this.offline.trustedTime = this.now(); this.offline.localTime = Date.now(); await this.options.storage.save(this.prefix + ".offline", JSON.stringify(this.offline)); } } async hasOfflineAccess() { return this.queued(async () => { if (!this.validOffline()) return false; try { await this.persistOffline(); return true; } catch { this.offline = undefined; return false; } }); } async hasAccess() { if (this.disposed || this.loggingOut) return false; if (this.token && this.deadline > this.now()) return true; return this.hasOfflineAccess(); } async logout(signal?: AbortSignal) { this.loggingOut = true; this.stopHeartbeat(); return this.queued(async () => { try { if (this.token) await this.request("/v3/session/logout", {}, true, false, signal); } finally { this.stopHeartbeat(); this.token = undefined; this.userData = {}; this.deadline = 0; await this.clearOffline(); } }); } private stopHeartbeat() { if (this.timer) clearTimeout(this.timer); this.timer = undefined; } private startHeartbeat() { this.stopHeartbeat(); if (this.options.automaticHeartbeat === false || this.disposed || !this.token) return; const delay = Math.max( 1, this.heartbeatSeconds + ((randomBytes(4).readUInt32LE() / 0xffffffff) * 2 - 1) * this.jitterSeconds, ) * 1000; this.timer = setTimeout(async () => { try { await this.checkSession(); } catch {} if (this.token && !this.disposed && !this.loggingOut) this.startHeartbeat(); }, delay); this.timer.unref(); } onResume(signal?: AbortSignal) { return this.checkSession(signal); } dispose() { if (this.disposed) return; this.disposed = true; this.stopHeartbeat(); this.controller.abort(); this.token = undefined; this.userData = {}; this.deadline = 0; this.state("disposed"); } } export { Runtime as Client }; function userDataFields(i: Record) { return { ...i, Username: i.type === "user" ? i.name : "", LicenseKey: i.licenseKey || (i.type === "license" ? i.name : ""), SID: i.systemId, Email: i.email, Plan: i.plan, ExpiryDate: i.expiry, Country: i.country, IpAddress: i.ipAddress, DeviceLimit: i.deviceLimit, }; } ``` # Complete Java V3 SDK source ```java // AuthlyX Java SDK Version 3.0 BETA package app.authlyx; import com.fasterxml.jackson.databind.*; import com.fasterxml.jackson.databind.node.*; import java.io.*; import java.io.IOException; import java.net.*; import java.net.http.*; import java.nio.*; import java.nio.charset.StandardCharsets; import java.nio.file.*; import java.nio.file.Path; import java.security.*; import java.security.spec.*; import java.time.*; import java.time.format.DateTimeFormatter; import java.util.*; import java.util.concurrent.*; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.*; import java.util.function.Consumer; import java.util.function.Function; import org.bouncycastle.crypto.params.Ed25519PrivateKeyParameters; public final class AuthlyX implements AutoCloseable { static final ObjectMapper JSON = new ObjectMapper().enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS); public static final class SdkException extends RuntimeException { public final String code, kind, requestId; public final int status; public SdkException(String code, String message, String kind) { this(code, message, kind, 0, null); } public SdkException(String code, String message, String kind, int status, String requestId) { super(message); this.code = code; this.kind = kind; this.status = status; this.requestId = requestId; } } public record Result(boolean success, String code, String message, JsonNode data, String requestId) { public boolean ok() { return success; } public boolean failed() { return !success; } public T decode(Class type) { try { return JSON.treeToValue(data, type); } catch (Exception e) { throw fail("DATA_INVALID", "The response data could not be decoded.", "security"); } } @Override public String toString() { return code; } } public static final class Options { public String heartbeat; public String appKey, version, systemId, endpoint, buildHash = ""; public Map responseKeys = Map.of(), offlineKeys = Map.of(), scriptKeys = Map.of(); public ProtectedStore storage; public Duration requestBudget = Duration.ofSeconds(8); public boolean manualHeartbeat = false, allowLocalHttp = false; public java.util.function.Consumer onConnection; public java.util.function.Consumer onInvalidated; } private final Options o; private final HttpClient http; private final PrivateKey key; private final String publicPem, keyHash, prefix; private final ExecutorService worker = Executors.newSingleThreadExecutor(r -> { Thread t = new Thread(r, "authlyx-v3"); t.setDaemon(true); return t; }); private final ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor(r -> { Thread t = new Thread(r, "authlyx-heartbeat"); t.setDaemon(true); return t; }); private final Set operations = ConcurrentHashMap.newKeySet(); private volatile boolean disposed, loggingOut; private ScheduledFuture heartbeat; public volatile JsonNode userData = JSON.createObjectNode(); private String token, sessionId, appId, identityId; private ObjectNode offline; private long anchorServer, anchorMono, anchorWall, deadline; private double heartbeatSeconds = 600, jitterSeconds = 15; private static final SecureRandom RANDOM = new SecureRandom(); private static final Set REVOKED = Set.of("SESSION_EXPIRED", "ACCESS_REVOKED", "APP_PAUSED", "ACCESS_EXPIRED", "ACCESS_DENIED", "IP_BLACKLISTED", "IP_NOT_WHITELISTED", "SID_BLACKLISTED", "SID_NOT_WHITELISTED", "VERSION_NOT_ALLOWED", "HASH_NOT_ALLOWED", "COUNTRY_BLOCKED", "VPN_NOT_ALLOWED", "DEVICE_NOT_ALLOWED", "INVALID_CREDENTIALS", "APP_DISABLED", "IP_BLOCKED", "SID_BLOCKED", "UPDATE_REQUIRED", "INVALID_HASH", "VPN_BLOCKED", "USER_BANNED", "USER_SUSPENDED", "USER_EXPIRED", "LICENSE_BANNED", "LICENSE_PAUSED", "LICENSE_EXPIRED", "MOTHERBOARD_BANNED", "MOTHERBOARD_PAUSED", "MOTHERBOARD_EXPIRED", "PROCESSOR_BANNED", "PROCESSOR_PAUSED", "PROCESSOR_EXPIRED"); private static SdkException fail(String code, String message, String kind) { return new SdkException(code, message, kind); } public static String hash(byte[] value) { try { return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(value)); } catch (GeneralSecurityException e) { throw new IllegalStateException("SHA-256 unavailable"); } } public static String hash(String value) { return hash(value.getBytes(StandardCharsets.UTF_8)); } private static byte[] random(int count) { byte[] b = new byte[count]; RANDOM.nextBytes(b); return b; } private static LinkedHashMap obj(Object... values) { var result = new LinkedHashMap(); for (int i = 0; i < values.length; i += 2) result.put((String)values[i], values[i + 1]); return result; } private static String json(Object value) { try { return JSON.writeValueAsString(value); } catch (Exception e) { throw fail("INVALID_ARGUMENT", "The request could not be encoded.", "server"); } } private static String text(JsonNode node, String name) { return node.path(name).asText(""); } private static PublicKey publicKey(String pem) throws GeneralSecurityException { return KeyFactory.getInstance("Ed25519").generatePublic(new X509EncodedKeySpec( Base64.getMimeDecoder().decode(pem.replace("-----BEGIN PUBLIC KEY-----", "") .replace("-----END PUBLIC KEY-----", "")))); } private static boolean verify(String pem, String payload, String signature) { try { var verifier = Signature.getInstance("Ed25519"); verifier.initVerify(publicKey(pem)); verifier.update(payload.getBytes(StandardCharsets.UTF_8)); return verifier.verify(Base64.getDecoder().decode(signature)); } catch (Exception e) { return false; } } private String sign(String payload) { try { var signer = Signature.getInstance("Ed25519"); signer.initSign(key); signer.update(payload.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(signer.sign()); } catch (GeneralSecurityException e) { throw fail("SIGNING_FAILED", "The installation signature could not be created.", "security"); } } public AuthlyX(String appKey, String version) { this(defaults(appKey, version)); } public static String systemId() { try { if (!System.getProperty("os.name").toLowerCase(Locale.ROOT).contains("windows")) throw new IllegalStateException("Supply a platform system ID through Options."); Process process = new ProcessBuilder( Path.of(System.getenv("SystemRoot"), "System32", "whoami.exe").toString(), "/user", "/fo", "csv", "/nh") .redirectErrorStream(true) .start(); if (!process.waitFor(3, TimeUnit.SECONDS)) { process.destroyForcibly(); throw new IOException("SID lookup timed out."); } String output = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8); var match = java.util.regex.Pattern.compile("S-1-\\d+(?:-\\d+)+").matcher(output); if (process.exitValue() != 0 || !match.find()) throw new IOException("Windows SID unavailable."); return match.group(); } catch (InterruptedException error) { Thread.currentThread().interrupt(); throw fail("SYSTEM_ID_UNAVAILABLE", "SID lookup interrupted.", "cancelled"); } catch (Exception error) { throw fail("SYSTEM_ID_UNAVAILABLE", "Could not read the Windows user SID.", "storage"); } } public static Options defaults(String appKey, String version) { Options o = new Options(); o.appKey = appKey; o.version = version; o.systemId = systemId(); o.endpoint = "https://api.authlyx.dev"; o.allowLocalHttp = true; try { o.storage = new WindowsProtectedStore(Path.of(System.getenv("LOCALAPPDATA"), "AuthlyX", "v3")); } catch (IOException error) { throw fail("STORAGE_UNAVAILABLE", "Could not open protected storage.", "storage"); } o.responseKeys = Map.of("2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052", "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n"); o.offlineKeys = Map.of("d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2", "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n"); o.scriptKeys = Map.of("5aec455eb0b10697", "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n"); return o; } public AuthlyX(Options source) { URI url = URI.create(source.endpoint); boolean local = Set.of("localhost", "127.0.0.1", "[::1]", "::1").contains(url.getHost()); if (url.getRawUserInfo() != null || url.getQuery() != null || url.getFragment() != null || (!url.getPath().isEmpty() && !url.getPath().equals("/")) || (!url.getScheme().equals("https") && !(source.allowLocalHttp && url.getScheme().equals("http") && local))) throw new IllegalArgumentException( "Use an HTTPS API origin. HTTP is limited to explicit loopback testing."); if (source.storage == null || source.responseKeys.isEmpty() || source.appKey == null || source.version == null || source.systemId == null || source.requestBudget.toMillis() < 100 || source.requestBudget.toMillis() > 60000) throw new IllegalArgumentException("Provide app identity, protected storage, trusted " + "response keys and a bounded request budget."); o = new Options(); o.appKey = source.appKey; o.version = source.version; o.systemId = source.systemId; o.endpoint = url.getScheme() + "://" + url.getRawAuthority(); o.buildHash = source.buildHash; o.responseKeys = Map.copyOf(source.responseKeys); o.offlineKeys = Map.copyOf(source.offlineKeys); o.scriptKeys = Map.copyOf(source.scriptKeys); o.storage = source.storage; o.requestBudget = source.requestBudget; if (source.heartbeat != null && !source.heartbeat.equals("server") && !source.heartbeat.equals("manual")) throw new IllegalArgumentException("Use server or manual heartbeat mode."); o.manualHeartbeat = source.heartbeat == null ? source.manualHeartbeat : source.heartbeat.equals("manual"); o.onConnection = source.onConnection; o.onInvalidated = source.onInvalidated; prefix = "authlyx.v3." + hash(o.endpoint + "/\n" + o.appKey + "\n" + o.systemId); try { String identityName = "authlyx.v3.installation." + hash(o.endpoint + "/\n" + o.systemId); String saved = o.storage.load(identityName); byte[] seed = saved == null ? random(32) : Base64.getDecoder().decode(saved); if (seed.length != 32) throw new IOException(); if (saved == null) o.storage.save(identityName, Base64.getEncoder().encodeToString(seed)); byte[] raw = new Ed25519PrivateKeyParameters(seed, 0).generatePublicKey().getEncoded(); byte[] der = ByteBuffer.allocate(44) .put(HexFormat.of().parseHex("302a300506032b6570032100")) .put(raw) .array(); key = KeyFactory.getInstance("Ed25519").generatePrivate(new PKCS8EncodedKeySpec( ByteBuffer.allocate(48) .put(HexFormat.of().parseHex("302e020100300506032b657004220420")) .put(seed) .array())); Arrays.fill(seed, (byte)0); publicPem = "-----BEGIN PUBLIC KEY-----\n" + Base64.getEncoder().encodeToString(der) + "\n-----END PUBLIC KEY-----\n"; keyHash = hash(der); saved = o.storage.load(prefix + ".offline"); if (saved != null) { offline = (ObjectNode)JSON.readTree(saved); appId = text(offline, "appId"); identityId = text(offline, "identityId"); long localTime = offline.path("localTime").asLong(); if (System.currentTimeMillis() < localTime) throw new IOException(); anchor(offline.path("trustedTime").asLong() + System.currentTimeMillis() - localTime); if (!validOffline()) clearOffline(); } } catch (Exception e) { throw fail("STORAGE_INVALID", "Protected SDK state could not be read or saved.", "storage"); } http = HttpClient.newBuilder() .followRedirects(HttpClient.Redirect.NEVER) .connectTimeout(o.requestBudget) .build(); } private static final class Operation { final AtomicBoolean cancelled = new AtomicBoolean(); volatile CompletableFuture wire; void check() { if (cancelled.get()) throw fail("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); } void cancel() { cancelled.set(true); if (wire != null) wire.cancel(true); } } private CompletableFuture async(Function action) { return async(action, false); } private CompletableFuture async(Function action, boolean alwaysRun) { if (disposed) return CompletableFuture.failedFuture( fail("DISPOSED", "This client is disposed.", "cancelled")); var context = new Operation(); var future = new CompletableFuture(); operations.add(context); future.whenComplete((v, e) -> { if (future.isCancelled()) context.cancel(); }); worker.execute(() -> { String before = token; try { if (!alwaysRun) context.check(); T result = action.apply(context); if (!future.complete(result) && before == null && token != null) { token = null; userData = JSON.createObjectNode(); deadline = 0; stopHeartbeat(); clearOffline(); } } catch (Throwable e) { future.completeExceptionally(e); } finally { operations.remove(context); } }); return future; } private void anchor(long value) { anchorServer = value; anchorMono = System.nanoTime(); anchorWall = System.currentTimeMillis(); } private long now() { return anchorServer == 0 ? System.currentTimeMillis() : anchorServer + (System.nanoTime() - anchorMono) / 1000000; } private void connection(String state) { if (o.onConnection != null) CompletableFuture.runAsync(() -> { try { o.onConnection.accept(state); } catch (Exception ignored) { } }); } private void clearOffline() { offline = null; try { o.storage.delete(prefix + ".offline"); } catch (IOException e) { throw fail("STORAGE_INVALID", "Protected offline state could not be removed.", "storage"); } } private void invalidate(SdkException error) { token = null; userData = JSON.createObjectNode(); deadline = 0; stopHeartbeat(); try { clearOffline(); } catch (SdkException ignored) { } if (o.onInvalidated != null) CompletableFuture.runAsync(() -> { try { o.onInvalidated.accept(error); } catch (Exception ignored) { } }); } private Result verified(JsonNode outer, int status, String path, String body, String nonce) { try { JsonNode proof = outer.path("verification"); String id = text(proof, "keyId"), pem = o.responseKeys.get(id), payload = text(proof, "signedPayload"); if (pem == null || payload.length() > 2000000 || !hash(publicKey(pem).getEncoded()).equals(id) || !verify(pem, payload, text(proof, "signature"))) throw new IOException(); JsonNode signed = JSON.readTree(payload); ObjectNode envelope = ((ObjectNode)outer).deepCopy(); envelope.remove("verification"); if (!text(signed, "type").equals("authlyx.response.v3") || !text(signed, "keyId").equals(id) || signed.path("httpStatus").asInt() != status || !signed.path("request").equals(JSON.valueToTree(obj( "method", "POST", "path", path, "nonce", nonce, "bodySha256", hash(body)))) || !signed.path("response").equals(envelope) || !envelope.path("message").isTextual() || !envelope.path("success").isBoolean() || !envelope.path("code").isTextual() || !envelope.path("requestId").isTextual()) throw new IOException(); anchor(Instant.parse(text(signed, "serverTime")).toEpochMilli()); return new Result(envelope.path("success").asBoolean(), text(envelope, "code"), text(envelope, "message"), envelope.path("data"), text(envelope, "requestId")); } catch (Exception e) { throw fail("RESPONSE_INVALID", "The server response could not be verified.", "security"); } } private static final class LimitedBody implements HttpResponse.BodySubscriber { private final CompletableFuture result = new CompletableFuture<>(); private final ByteArrayOutputStream bytes = new ByteArrayOutputStream(); private Flow.Subscription subscription; public CompletionStage getBody() { return result; } public void onSubscribe(Flow.Subscription value) { subscription = value; value.request(Long.MAX_VALUE); } public void onNext(List values) { for (var value : values) { if (bytes.size() + value.remaining() > 2000000) { subscription.cancel(); result.completeExceptionally( fail("RESPONSE_INVALID", "The server response is too large.", "security")); return; } byte[] chunk = new byte[value.remaining()]; value.get(chunk); bytes.writeBytes(chunk); } } public void onError(Throwable error) { result.completeExceptionally(error); } public void onComplete() { result.complete(bytes.toByteArray()); } } private Result request(Operation context, String path, Object data, boolean auth, boolean retry) { context.check(); if (auth && token == null) throw fail("NOT_SIGNED_IN", "Sign in before using this feature.", "server"); String body = json(data); long until = System.nanoTime() + o.requestBudget.toNanos(); for (int attempt = 0;; attempt++) { context.check(); String nonce = HexFormat.of().formatHex(random(24)), stamp = Long.toString(now()); try { long remaining = until - System.nanoTime(); if (remaining <= 0) throw new TimeoutException(); var builder = HttpRequest.newBuilder(URI.create(o.endpoint + path)) .timeout(Duration.ofNanos(remaining)) .header("Content-Type", "application/json") .header("X-AuthlyX-Nonce", nonce) .POST(HttpRequest.BodyPublishers.ofString(body)); if (auth) builder.header("Authorization", "Bearer " + token) .header("X-AuthlyX-Timestamp", stamp) .header( "X-AuthlyX-Signature", sign(json(obj("type", "authlyx.request.v3", "method", "POST", "path", path, "bodySha256", hash(body), "nonce", nonce, "timestamp", stamp, "tokenHash", hash(token))))); var wire = http.sendAsync(builder.build(), ignored -> new LimitedBody()); context.wire = wire; HttpResponse response; try { response = wire.get(remaining, TimeUnit.NANOSECONDS); } catch (TimeoutException e) { wire.cancel(true); throw e; } finally { context.wire = null; } context.check(); JsonNode outer; try { outer = JSON.readTree(response.body()); } catch (Exception e) { throw fail( response.statusCode() >= 500 ? "SERVICE_UNAVAILABLE" : "RESPONSE_INVALID", response.statusCode() >= 500 ? "The service is temporarily unavailable." : "The server response is not valid JSON.", response.statusCode() >= 500 ? "network" : "security"); } if (!outer.has("verification") && response.statusCode() >= 500) throw fail("SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network"); Result result = verified(outer, response.statusCode(), path, body, nonce); connection("online"); if (!result.success() || response.statusCode() >= 400) { String kind = response.statusCode() == 429 || response.statusCode() >= 500 ? "network" : "server"; if (retry && attempt < 2 && (kind.equals("network") || result.code().equals("REQUEST_TIME_INVALID"))) { String after = response.headers().firstValue("Retry-After").orElse(""); long delay = 150; try { delay = after.isEmpty() ? 150 : after.matches("[0-9]+") ? Math.multiplyExact(Long.parseLong(after), 1000) : ZonedDateTime .parse(after, DateTimeFormatter.RFC_1123_DATE_TIME) .toInstant() .toEpochMilli() - System.currentTimeMillis(); } catch (Exception e) { delay = o.requestBudget.toMillis(); } if (delay >= 0 && System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(delay + 50) < until) { Thread.sleep(delay); continue; } } throw new SdkException(result.code(), result.message(), kind, response.statusCode(), result.requestId()); } return result; } catch (SdkException e) { if (e.kind.equals("security")) { connection("untrusted"); invalidate(e); } else if (e.kind.equals("network")) connection("disconnected"); else if (auth && REVOKED.contains(e.code)) invalidate(e); throw e; } catch (CancellationException e) { throw fail("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw fail("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); } catch (TimeoutException e) { connection("disconnected"); throw fail("NETWORK_TIMEOUT", "The request timed out. Try again when connected.", "network"); } catch (ExecutionException e) { if (e.getCause() instanceof SdkException failure) { invalidate(failure); throw failure; } context.check(); connection("disconnected"); if (retry && attempt < 2 && System.nanoTime() + TimeUnit.MILLISECONDS.toNanos(200) < until) { try { Thread.sleep(150); } catch (InterruptedException ignored) { Thread.currentThread().interrupt(); throw fail("REQUEST_CANCELLED", "The request was cancelled.", "cancelled"); } continue; } throw fail("NETWORK_ERROR", "Could not connect to AuthlyX.", "network"); } } } public CompletableFuture initialize() { return init(); } public CompletableFuture initialize(Consumer callback) { return init(callback); } public CompletableFuture init() { return async(c -> request(c, "/v3/initialize", obj("appKey", o.appKey, "version", o.version), false, true)); } public CompletableFuture registerUser(String username, String password, String licenseKey) { return loginImpl("register", username, password, licenseKey); } public CompletableFuture changePassword(String currentPassword, String newPassword) { return protectedCall("/v3/account/password", obj("currentPassword", currentPassword, "newPassword", newPassword), false); } public CompletableFuture redeemLicense(String licenseKey) { return protectedCall("/v3/licenses/redeem", obj("licenseKey", licenseKey), false); } public CompletableFuture log(String message) { return protectedCall("/v3/logs/add", obj("message", message), false); } public CompletableFuture login(String license) { return licenseLogin(license); } public CompletableFuture login(String username, String password) { return loginImpl("user", username, password, ""); } public CompletableFuture licenseLogin(String license) { return loginImpl("license", "", "", license); } public CompletableFuture deviceLogin() { return loginImpl("device", "", "", ""); } private CompletableFuture loginImpl(String type, String username, String password, String license) { return async(c -> { if (token != null) throw fail("ALREADY_SIGNED_IN", "Sign out before starting another session.", "server"); clearOffline(); loggingOut = false; JsonNode challenge = request(c, "/v3/challenge", obj("appKey", o.appKey, "installationPublicKey", publicPem), false, false) .data(); var operation = obj("type", type, "appKey", o.appKey, "version", o.version, "sid", o.systemId, "hash", o.buildHash, "username", username, "password", password, "licenseKey", license); String signature = sign(json(obj("challenge", text(challenge, "payload"), "operation", operation))); operation.put("challengeId", text(challenge, "challengeId")); operation.put("signature", signature); Result result = request(c, "/v3/login", operation, false, false); c.check(); try { appId = text(JSON.readTree(text(challenge, "payload")), "appId"); } catch (IOException e) { throw fail("RESPONSE_INVALID", "Invalid challenge.", "security"); } ObjectNode identity = ((ObjectNode)result.data().get("identity")).deepCopy(); for (String[] pair : new String[][] {{"SID", "systemId"}, {"Email", "email"}, {"Plan", "plan"}, {"ExpiryDate", "expiry"}, {"Country", "country"}, {"IpAddress", "ipAddress"}, {"DeviceLimit", "deviceLimit"}}) identity.set(pair[0], identity.get(pair[1])); identity.put("Username", text(identity, "type").equals("user") ? text(identity, "name") : ""); identity.put("LicenseKey", text(identity, "licenseKey")); userData = identity; token = text(result.data(), "token"); sessionId = text(result.data(), "sessionId"); identityId = text(result.data(), "identityId"); lease(result.data()); ObjectNode safe = ((ObjectNode)result.data()).deepCopy(); safe.remove("token"); startHeartbeat(); return new Result(result.success(), result.code(), result.message(), safe, result.requestId()); }); } private void lease(JsonNode data) { long value; try { value = Instant.parse(text(data, "accessDeadline")).toEpochMilli(); if (value <= 0 || value > now() + 7200100) throw new IllegalArgumentException(); } catch (Exception e) { SdkException error = fail("LEASE_INVALID", "The session deadline is invalid.", "security"); invalidate(error); throw error; } deadline = value; ObjectNode refreshed = userData.isObject() ? ((ObjectNode)userData).deepCopy() : JSON.createObjectNode(); for (String key : new String[] {"features", "featureValues", "metadata"}) { if (data.has(key)) refreshed.set(key, data.get(key).deepCopy()); } userData = refreshed; heartbeatSeconds = Math.max(1, Math.min(3600, data.path("heartbeatSeconds").asDouble(600))); jitterSeconds = Math.max(0, Math.min(15, data.path("jitterSeconds").asDouble(15))); } public CompletableFuture checkSession() { return async(c -> { Result result = request(c, "/v3/session/check", obj(), true, true); lease(result.data()); return result; }); } private CompletableFuture protectedCall(String path, Object data, boolean retry) { return async(c -> { if (token != null && deadline <= now()) lease(request(c, "/v3/session/check", obj(), true, true).data()); return request(c, path, data, true, retry); }); } private CompletableFuture complete(CompletableFuture operation, Consumer callback) { Objects.requireNonNull(callback, "A completion callback is required."); return operation .handle((result, failure) -> { if (failure == null) return result; Throwable error = failure instanceof CompletionException && failure.getCause() != null ? failure.getCause() : failure; return new Result(false, error instanceof SdkException sdk ? sdk.code : "CLIENT_ERROR", error.getMessage(), NullNode.instance, error instanceof SdkException sdk ? sdk.requestId : ""); }) .thenAccept(callback); } public CompletableFuture init(Consumer callback) { return complete(init(), callback); } public CompletableFuture licenseLogin(String key, Consumer callback) { return complete(licenseLogin(key), callback); } public CompletableFuture login(String username, String password, Consumer callback) { return complete(login(username, password), callback); } public CompletableFuture getVariable(String name, Consumer callback) { return complete(getVariable(name), callback); } public CompletableFuture getScriptWithCallback(String name, Consumer callback) { return complete(getScript(name, null), callback); } public CompletableFuture getMetadata() { return protectedCall("/v3/metadata/get", obj(), true); } public CompletableFuture getMetadata(String key) { return protectedCall("/v3/metadata/get", obj("key", key), true); } public CompletableFuture updateVariable(String name, String value) { return protectedCall("/v3/data/set", obj("name", name, "value", value), false); } public CompletableFuture getFeatures() { return protectedCall("/v3/features/list", obj(), true); } public CompletableFuture getFeature(String name) { return protectedCall("/v3/features/get", obj("name", name), true); } public CompletableFuture getAllMetadata() { return protectedCall("/v3/metadata/list", obj(), true); } public CompletableFuture checkMetadata(String key) { return protectedCall("/v3/metadata/check", obj("key", key), true); } public CompletableFuture sendWebhook(String name, Object data) { return protectedCall("/v3/webhooks/send", obj("event", name, "data", data), false); } public CompletableFuture setMetadata(String key, Object value) { return protectedCall("/v3/metadata/set", obj("key", key, "value", value), false); } public CompletableFuture checkFeature(String name) { return protectedCall("/v3/features/check", obj("name", name), true); } public CompletableFuture getVariable(String name) { return protectedCall("/v3/data/get", obj("name", name), true); } public CompletableFuture getScript(String name, Integer revision) { var data = obj("name", name); if (revision != null) data.put("revision", revision); return protectedCall("/v3/scripts/get", data, true).thenApply(result -> { try { String payload = text(result.data(), "signedPayload"); JsonNode manifest = JSON.readTree(payload); if (manifest.has("issuedAt") || manifest.has("expiresAt")) { if (!manifest.path("issuedAt").isIntegralNumber() || !manifest.path("expiresAt").isIntegralNumber() || manifest.path("issuedAt").asLong() > now() + 30000 || manifest.path("expiresAt").asLong() <= now() || manifest.path("expiresAt").asLong() <= manifest.path("issuedAt").asLong()) throw new IOException(); } if (manifest.has("minimumRevision") && (!manifest.path("minimumRevision").isIntegralNumber() || manifest.path("revision").asInt() < manifest.path("minimumRevision").asInt())) throw new IOException(); String pem = o.scriptKeys.get(text(manifest, "keyId")), content = text(result.data(), "content"); if (pem == null || !verify(pem, payload, text(result.data(), "signature")) || !manifest.equals(result.data().path("manifest")) || !text(manifest, "appId").equals(appId) || !text(manifest, "name").equals(name) || (revision != null && manifest.path("revision").asInt() != revision) || !text(manifest, "sha256").equals(hash(content)) || manifest.path("bytes").asInt() != content.getBytes(StandardCharsets.UTF_8).length) throw new IOException(); return result; } catch (Exception e) { throw fail("SCRIPT_INVALID", "The script could not be verified.", "security"); } }); } public CompletableFuture saveOfflineAccess() { return async(c -> { JsonNode challenge = request(c, "/v3/offline/challenge", obj(), true, false).data(); String signature = sign(json(obj("challenge", text(challenge, "payload"), "operation", obj("action", "offlinePermit", "sessionId", sessionId)))); Result result = request(c, "/v3/offline/permit", obj("challengeId", text(challenge, "challengeId"), "signature", signature), true, false); offline = JSON.valueToTree(obj("appId", appId, "identityId", identityId, "permit", result.data(), "trustedTime", now(), "localTime", System.currentTimeMillis())); if (!validOffline()) { clearOffline(); throw fail("OFFLINE_INVALID", "The offline permit could not be verified.", "security"); } persist(); return result; }); } private boolean validOffline() { try { if (offline == null || disposed || loggingOut || System.currentTimeMillis() < anchorWall) return false; JsonNode permit = offline.path("permit"); String payload = text(permit, "signedPayload"); if (payload.length() > 4096) return false; JsonNode claims = JSON.readTree(payload); String id = text(claims, "keyId"), pem = o.offlineKeys.get(id); long issued = claims.path("issuedAt").asLong(Long.MAX_VALUE), expires = claims.path("expiresAt").asLong(Long.MIN_VALUE), current = now(); return pem != null && hash(publicKey(pem).getEncoded()).equals(id) && verify(pem, payload, text(permit, "signature")) && text(claims, "type").equals("authlyx.offline.v1") && text(claims, "appId").equals(appId) && text(claims, "subjectId").equals(identityId) && text(claims, "installationKeyHash").equals(keyHash) && issued <= current && current < expires && expires > issued && expires - issued <= 2592000000L && current >= offline.path("trustedTime").asLong(); } catch (Exception e) { return false; } } private void persist() { offline.put("trustedTime", now()); offline.put("localTime", System.currentTimeMillis()); try { o.storage.save(prefix + ".offline", json(offline)); } catch (IOException e) { offline = null; throw fail("STORAGE_INVALID", "Could not save protected offline state.", "storage"); } } public CompletableFuture hasOfflineAccess() { return async(c -> { if (!validOffline()) return false; try { persist(); return true; } catch (SdkException e) { return false; } }); } public CompletableFuture hasAccess() { return async(c -> { if (disposed || loggingOut) return false; if (token != null && deadline > now()) return true; if (!validOffline()) return false; try { persist(); return true; } catch (SdkException e) { return false; } }); } public CompletableFuture logout() { loggingOut = true; stopHeartbeat(); return async(c -> { try { if (token != null) request(c, "/v3/session/logout", obj(), true, false); } finally { stopHeartbeat(); token = null; userData = JSON.createObjectNode(); deadline = 0; clearOffline(); } return null; }, true); } private synchronized void stopHeartbeat() { if (heartbeat != null) { heartbeat.cancel(false); heartbeat = null; } } private synchronized void startHeartbeat() { stopHeartbeat(); if (o.manualHeartbeat || disposed || loggingOut || token == null) return; long delay = (long)(Math.max(1, heartbeatSeconds + (RANDOM.nextDouble() * 2 - 1) * jitterSeconds) * 1000); heartbeat = scheduler.schedule(() -> checkSession().whenComplete((v, e) -> { if (!disposed && !loggingOut && token != null) startHeartbeat(); }), delay, TimeUnit.MILLISECONDS); } public CompletableFuture onResume() { return checkSession(); } @Override public void close() { if (disposed) return; disposed = true; stopHeartbeat(); for (var operation : operations) operation.cancel(); scheduler.shutdownNow(); worker.shutdown(); token = null; userData = JSON.createObjectNode(); deadline = 0; } public interface ProtectedStore { String load(String name) throws IOException; void save(String name, String value) throws IOException; void delete(String name) throws IOException; } public static final class MemoryStore implements ProtectedStore { private final ConcurrentHashMap values = new ConcurrentHashMap<>(); public String load(String name) { return values.get(name); } public void save(String name, String value) { values.put(name, value); } public void delete(String name) { values.remove(name); } } public static final class WindowsProtectedStore implements ProtectedStore { private final Path directory; private static final String SCRIPT = "$ErrorActionPreference='Stop';try{Add-Type -AssemblyName " + "System.Security;$x=[Console]::In.ReadToEnd()|ConvertFrom-Json;$v=[Convert]::" + "FromBase64String($x.value);$e=[Convert]::FromBase64String($x.entropy);if($x.mode" + " -eq " + "'protect'){$o=[Security.Cryptography.ProtectedData]::Protect($v,$e,[Security." + "Cryptography." + "DataProtectionScope]::CurrentUser)}else{$o=[Security.Cryptography.ProtectedData]::" + "Unprotect($v,$e,[Security.Cryptography.DataProtectionScope]::CurrentUser)};[" + "Console]::Out.Write([Convert]::ToBase64String($o))}catch{exit" + " 1}"; public WindowsProtectedStore(Path directory) throws IOException { if (!System.getProperty("os.name").toLowerCase(Locale.ROOT).startsWith("windows")) throw new IOException("Supply a platform-protected store."); this.directory = directory.toAbsolutePath(); Files.createDirectories(this.directory); } private Path file(String name) { return directory.resolve(AuthlyX.hash(name) + ".dat"); } private byte[] crypt(String name, byte[] value, String mode) throws IOException { Process process = new ProcessBuilder("powershell.exe", "-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", SCRIPT) .redirectError(ProcessBuilder.Redirect.DISCARD) .start(); try { try (var stream = process.getOutputStream()) { stream.write(AuthlyX.JSON.writeValueAsBytes(Map.of( "mode", mode, "value", Base64.getEncoder().encodeToString(value), "entropy", Base64.getEncoder().encodeToString( name.getBytes(StandardCharsets.UTF_8))))); } var output = java.util.concurrent.CompletableFuture.supplyAsync(() -> { try { return process.getInputStream().readNBytes(1500000); } catch (IOException e) { return new byte[0]; } }); if (!process.waitFor(10, TimeUnit.SECONDS) || process.exitValue() != 0) throw new IOException("Protected state could not be read or saved."); return Base64.getDecoder().decode(output.get(1, TimeUnit.SECONDS)); } catch (Exception e) { throw new IOException("Protected storage is unavailable."); } finally { process.destroyForcibly(); } } public String load(String name) throws IOException { Path file = file(name); if (!Files.exists(file)) return null; byte[] bytes = Files.readAllBytes(file); if (bytes.length > 1048576) throw new IOException("Protected state is too large."); return new String(crypt(name, bytes, "unprotect"), StandardCharsets.UTF_8); } public void save(String name, String value) throws IOException { Path temp = Files.createTempFile(directory, ".authlyx-", ".tmp"); try { Files.write(temp, crypt(name, value.getBytes(StandardCharsets.UTF_8), "protect")); Files.move(temp, file(name), StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING); } finally { Files.deleteIfExists(temp); } } public void delete(String name) throws IOException { Files.deleteIfExists(file(name)); } } } ``` # Complete Go V3 SDK source ```go // AuthlyX Go SDK Version 3.0 BETA package authlyx import ( "bytes" "context" "crypto/ed25519" "crypto/rand" "crypto/sha256" "crypto/x509" "encoding/base64" "encoding/binary" "encoding/hex" "encoding/json" "encoding/pem" "errors" "fmt" "io" "net/http" "net/url" "os" "os/exec" "path/filepath" "reflect" "regexp" "runtime" "strconv" "strings" "sync" "time" "unicode/utf8" ) type Error struct { Code, Message, Kind, RequestID string Status int } func (e *Error) Error() string { return e.Code + ": " + e.Message } func failure(code, message, kind string) *Error { return &Error{Code: code, Message: message, Kind: kind} } type Result struct { Success bool `json:"success"` Code string `json:"code"` Message string `json:"message"` RequestID string `json:"requestId"` Data map[string]any `json:"data"` } func (r Result) String() string { return r.Code } func DecodeData[T any](r Result) (T, error) { var result T b, e := json.Marshal(r.Data) if e == nil { e = json.Unmarshal(b, &result) } return result, e } type Store interface { Load(context.Context, string) (string, error) Save(context.Context, string, string) error Delete(context.Context, string) error } type MemoryStore struct { mu sync.Mutex values map[string]string } func (s *MemoryStore) Load(_ context.Context, k string) (string, error) { s.mu.Lock() defer s.mu.Unlock() return s.values[k], nil } func (s *MemoryStore) Save(_ context.Context, k, v string) error { s.mu.Lock() defer s.mu.Unlock() if s.values == nil { s.values = map[string]string{} } s.values[k] = v return nil } func (s *MemoryStore) Delete(_ context.Context, k string) error { s.mu.Lock() defer s.mu.Unlock() delete(s.values, k) return nil } type Options struct { Heartbeat string AppKey, Version, SystemID, BuildHash, Endpoint string ResponseKeys, OfflineKeys, ScriptKeys map[string]string Storage Store RequestBudget time.Duration ManualHeartbeat, AllowLocalHTTP bool OnConnection func(string) OnInvalidated func(*Error) } type offlineState struct { AppID string `json:"appId"` IdentityID string `json:"identityId"` Permit map[string]string `json:"permit"` TrustedTime int64 `json:"trustedTime"` LocalTime int64 `json:"localTime"` } type AuthlyX struct { userData map[string]any o Options http *http.Client key ed25519.PrivateKey publicPEM, installationHash, prefix, token, sessionID, appID, identityID string offline *offlineState serverTime, wallTime int64 anchor time.Time deadline int64 heartbeatSeconds, jitterSeconds float64 gate chan struct{} life context.Context cancel context.CancelFunc heartbeatCancel context.CancelFunc disposed, loggingOut bool events chan func() } func hash(v []byte) string { sum := sha256.Sum256(v); return hex.EncodeToString(sum[:]) } func random(n int) []byte { v := make([]byte, n) if _, e := rand.Read(v); e != nil { panic("OS random source unavailable") } return v } func publicKey(value string) (ed25519.PublicKey, error) { b, _ := pem.Decode([]byte(value)) if b == nil { return nil, errors.New("invalid public key") } k, e := x509.ParsePKIXPublicKey(b.Bytes) if e != nil { return nil, e } p, ok := k.(ed25519.PublicKey) if !ok { return nil, errors.New("not Ed25519") } return p, nil } func fingerprint(k ed25519.PublicKey) string { b, _ := x509.MarshalPKIXPublicKey(k); return hash(b) } func verifySignature(value, payload, signature string) bool { k, e := publicKey(value) if e != nil { return false } sig, e := base64.StdEncoding.DecodeString(signature) return e == nil && ed25519.Verify(k, []byte(payload), sig) } func quote(v string) string { var b strings.Builder b.WriteByte('"') for _, r := range v { switch r { case '"': b.WriteString(`\"`) case '\\': b.WriteString(`\\`) case '\b': b.WriteString(`\b`) case '\f': b.WriteString(`\f`) case '\n': b.WriteString(`\n`) case '\r': b.WriteString(`\r`) case '\t': b.WriteString(`\t`) default: if r < 32 { fmt.Fprintf(&b, `\u%04x`, r) } else { b.WriteRune(r) } } } b.WriteByte('"') return b.String() } type pair struct{ k, v string } func object(fields ...pair) string { var b strings.Builder b.WriteByte('{') for i, p := range fields { if i > 0 { b.WriteByte(',') } b.WriteString(quote(p.k)) b.WriteByte(':') b.WriteString(p.v) } b.WriteByte('}') return b.String() } func text(k, v string) pair { return pair{k, quote(v)} } func stringValue(v any) string { s, _ := v.(string); return s } func number(v any) float64 { switch n := v.(type) { case json.Number: f, _ := n.Float64() return f case float64: return n } return 0 } func decode(b []byte) (map[string]any, error) { var v map[string]any d := json.NewDecoder(bytes.NewReader(b)) d.UseNumber() e := d.Decode(&v) if e == nil { var extra any if d.Decode(&extra) != io.EOF { return nil, failure("RESPONSE_INVALID", "Unexpected trailing JSON.", "security") } } return v, e } func clone(v map[string]string) map[string]string { r := map[string]string{} for k, p := range v { r[k] = p } return r } func New(ctx context.Context, o Options) (*AuthlyX, error) { if o.Heartbeat != "" { if o.Heartbeat != "server" && o.Heartbeat != "manual" { return nil, errors.New("use server or manual heartbeat mode") } o.ManualHeartbeat = o.Heartbeat == "manual" } u, e := url.Parse(o.Endpoint) if e != nil { return nil, e } local := u.Hostname() == "127.0.0.1" || u.Hostname() == "localhost" || u.Hostname() == "::1" if u.User != nil || u.RawQuery != "" || u.Fragment != "" || (u.Path != "" && u.Path != "/") || (u.Scheme != "https" && !(o.AllowLocalHTTP && u.Scheme == "http" && local)) { return nil, errors.New("use an HTTPS API origin; HTTP is limited to explicit loopback testing") } if o.Storage == nil || o.AppKey == "" || o.Version == "" || o.SystemID == "" || len(o.ResponseKeys) == 0 { return nil, errors.New("provide app identity, protected storage and trusted response keys") } if o.RequestBudget == 0 { o.RequestBudget = 8 * time.Second } if o.RequestBudget < 100*time.Millisecond || o.RequestBudget > time.Minute { return nil, errors.New("request budget must be 100 ms to 60 seconds") } o.ResponseKeys = clone(o.ResponseKeys) o.OfflineKeys = clone(o.OfflineKeys) o.ScriptKeys = clone(o.ScriptKeys) o.Endpoint = u.Scheme + "://" + u.Host life, cancel := context.WithCancel(context.Background()) c := &AuthlyX{o: o, gate: make(chan struct{}, 1), life: life, cancel: cancel, heartbeatSeconds: 600, jitterSeconds: 15, events: make(chan func(), 32)} c.http = &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }, Transport: &http.Transport{Proxy: http.ProxyFromEnvironment, ForceAttemptHTTP2: true, TLSHandshakeTimeout: o.RequestBudget}} c.prefix = "authlyx.v3." + hash([]byte(o.Endpoint+"/\n"+o.AppKey+"\n"+o.SystemID)) identityName := "authlyx.v3.installation." + hash([]byte(o.Endpoint+"/\n"+o.SystemID)) saved, e := o.Storage.Load(ctx, identityName) if e != nil { return nil, failure("STORAGE_INVALID", "Protected state could not be read.", "storage") } var seed []byte if saved == "" { seed = random(32) e = o.Storage.Save(ctx, identityName, base64.StdEncoding.EncodeToString(seed)) } else { seed, e = base64.StdEncoding.DecodeString(saved) } if e != nil || len(seed) != 32 { return nil, failure("STORAGE_INVALID", "Protected installation key is invalid.", "storage") } c.key = ed25519.NewKeyFromSeed(seed) for i := range seed { seed[i] = 0 } pub := c.key.Public().(ed25519.PublicKey) der, _ := x509.MarshalPKIXPublicKey(pub) c.publicPEM = string(pem.EncodeToMemory(&pem.Block{Type: "PUBLIC KEY", Bytes: der})) c.installationHash = hash(der) saved, e = o.Storage.Load(ctx, c.prefix+".offline") if e != nil { return nil, failure("STORAGE_INVALID", "Protected state could not be read.", "storage") } if saved != "" { if json.Unmarshal([]byte(saved), &c.offline) != nil || c.offline == nil || time.Now().UnixMilli() < c.offline.LocalTime { return nil, failure("STORAGE_INVALID", "Protected offline state is invalid.", "storage") } c.appID = c.offline.AppID c.identityID = c.offline.IdentityID c.setAnchor(c.offline.TrustedTime + time.Now().UnixMilli() - c.offline.LocalTime) if !c.validOffline() { if e = c.clearOffline(ctx); e != nil { return nil, e } } } go func() { for { select { case f := <-c.events: func() { defer func() { _ = recover() }(); f() }() case <-c.life.Done(): return } } }() return c, nil } func (c *AuthlyX) lock(ctx context.Context) error { select { case c.gate <- struct{}{}: if c.disposed { <-c.gate return failure("DISPOSED", "This client is disposed.", "cancelled") } return nil case <-ctx.Done(): return ctx.Err() case <-c.life.Done(): return c.life.Err() } } func (c *AuthlyX) unlock() { <-c.gate } func (c *AuthlyX) setAnchor(ms int64) { c.serverTime = ms c.anchor = time.Now() c.wallTime = time.Now().UnixMilli() } func (c *AuthlyX) now() int64 { if c.serverTime == 0 { return time.Now().UnixMilli() } return c.serverTime + time.Since(c.anchor).Milliseconds() } func (c *AuthlyX) emit(f func()) { select { case c.events <- f: default: } } func (c *AuthlyX) connection(state string) { if c.o.OnConnection != nil { c.emit(func() { c.o.OnConnection(state) }) } } func (c *AuthlyX) clearOffline(ctx context.Context) error { c.offline = nil return c.o.Storage.Delete(ctx, c.prefix+".offline") } func (c *AuthlyX) invalidate(ctx context.Context, e *Error) { c.token = "" c.userData = nil c.deadline = 0 c.stopHeartbeat() _ = c.clearOffline(ctx) if c.o.OnInvalidated != nil { c.emit(func() { c.o.OnInvalidated(e) }) } } func (c *AuthlyX) verify(outer map[string]any, status int, path, body, nonce string) (Result, error) { bad := failure("RESPONSE_INVALID", "The server response could not be verified.", "security") proof, ok := outer["verification"].(map[string]any) if !ok { return Result{}, bad } id := stringValue(proof["keyId"]) p := c.o.ResponseKeys[id] key, e := publicKey(p) payload := stringValue(proof["signedPayload"]) if e != nil || fingerprint(key) != id || len(payload) > 2000000 || !verifySignature(p, payload, stringValue(proof["signature"])) { return Result{}, bad } signed, e := decode([]byte(payload)) if e != nil { return Result{}, bad } request, ok := signed["request"].(map[string]any) if !ok { return Result{}, bad } delete(outer, "verification") if signed["type"] != "authlyx.response.v3" || signed["keyId"] != id || int(number(signed["httpStatus"])) != status || request["method"] != "POST" || request["path"] != path || request["nonce"] != nonce || request["bodySha256"] != hash([]byte(body)) || !reflect.DeepEqual(signed["response"], outer) { return Result{}, bad } server, e := time.Parse(time.RFC3339Nano, stringValue(signed["serverTime"])) if e != nil { return Result{}, bad } c.setAnchor(server.UnixMilli()) _, messageOK := outer["message"].(string) success, ok := outer["success"].(bool) if !ok || !messageOK { return Result{}, bad } data, _ := outer["data"].(map[string]any) result := Result{Success: success, Code: stringValue(outer["code"]), Message: stringValue(outer["message"]), RequestID: stringValue(outer["requestId"]), Data: data} if result.Code == "" || result.RequestID == "" { return Result{}, bad } return result, nil } func (c *AuthlyX) request(ctx context.Context, path, body string, auth, retry bool) (Result, error) { if auth && c.token == "" { return Result{}, failure("NOT_SIGNED_IN", "Sign in before using this feature.", "server") } budget, cancel := context.WithTimeout(ctx, c.o.RequestBudget) defer cancel() goCancel := context.AfterFunc(c.life, cancel) defer goCancel() var last error for attempt := 0; attempt < 3; attempt++ { nonce := hex.EncodeToString(random(24)) stamp := strconv.FormatInt(c.now(), 10) request, e := http.NewRequestWithContext(budget, "POST", c.o.Endpoint+path, strings.NewReader(body)) if e != nil { return Result{}, e } request.Header.Set("Content-Type", "application/json") request.Header.Set("X-AuthlyX-Nonce", nonce) if auth { proof := object(text("type", "authlyx.request.v3"), text("method", "POST"), text("path", path), text("bodySha256", hash([]byte(body))), text("nonce", nonce), text("timestamp", stamp), text("tokenHash", hash([]byte(c.token)))) request.Header.Set("Authorization", "Bearer "+c.token) request.Header.Set("X-AuthlyX-Timestamp", stamp) request.Header.Set("X-AuthlyX-Signature", base64.StdEncoding.EncodeToString(ed25519.Sign(c.key, []byte(proof)))) } response, e := c.http.Do(request) delay := 150 * time.Millisecond if e != nil { if ctx.Err() != nil { return Result{}, ctx.Err() } last = failure("NETWORK_ERROR", "Could not connect to AuthlyX.", "network") } else { data, readError := io.ReadAll(io.LimitReader(response.Body, 2000001)) _ = response.Body.Close() if readError != nil { last = failure("NETWORK_ERROR", "Could not read the server response.", "network") } else if len(data) > 2000000 { last = failure("RESPONSE_INVALID", "The server response is too large.", "security") } else { outer, parseError := decode(data) if (parseError != nil || outer["verification"] == nil) && response.StatusCode >= 500 { last = failure("SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network") } else if parseError != nil { last = failure("RESPONSE_INVALID", "The server response is not valid JSON.", "security") } else { result, verifyError := c.verify(outer, response.StatusCode, path, body, nonce) if verifyError != nil { last = verifyError } else if response.StatusCode >= 400 || !result.Success { kind := "server" if response.StatusCode == 429 || response.StatusCode >= 500 { kind = "network" } last = &Error{Code: result.Code, Message: result.Message, Kind: kind, Status: response.StatusCode, RequestID: result.RequestID} if result.Code == "REQUEST_TIME_INVALID" && retry && attempt < 2 { continue } } else { c.connection("online") return result, nil } } } if after := response.Header.Get("Retry-After"); after != "" { if n, e := strconv.Atoi(after); e == nil { delay = time.Duration(n) * time.Second } else if t, e := http.ParseTime(after); e == nil { delay = time.Until(t) } else { delay = c.o.RequestBudget } } } var problem *Error if errors.As(last, &problem) { if problem.Kind == "security" { c.connection("untrusted") c.invalidate(context.Background(), problem) return Result{}, last } if problem.Kind == "server" { if auth && (problem.Code == "SESSION_EXPIRED" || problem.Code == "ACCESS_REVOKED" || problem.Code == "APP_PAUSED" || problem.Code == "ACCESS_EXPIRED" || problem.Code == "ACCESS_DENIED" || problem.Code == "IP_BLACKLISTED" || problem.Code == "IP_NOT_WHITELISTED" || problem.Code == "SID_BLACKLISTED" || problem.Code == "SID_NOT_WHITELISTED" || problem.Code == "VERSION_NOT_ALLOWED" || problem.Code == "HASH_NOT_ALLOWED" || problem.Code == "COUNTRY_BLOCKED" || problem.Code == "VPN_NOT_ALLOWED" || problem.Code == "DEVICE_NOT_ALLOWED" || problem.Code == "APP_DISABLED" || problem.Code == "IP_BLOCKED" || problem.Code == "SID_BLOCKED" || problem.Code == "UPDATE_REQUIRED" || problem.Code == "INVALID_HASH" || problem.Code == "VPN_BLOCKED" || problem.Code == "USER_BANNED" || problem.Code == "USER_SUSPENDED" || problem.Code == "USER_EXPIRED" || problem.Code == "LICENSE_BANNED" || problem.Code == "LICENSE_PAUSED" || problem.Code == "LICENSE_EXPIRED" || problem.Code == "MOTHERBOARD_BANNED" || problem.Code == "MOTHERBOARD_PAUSED" || problem.Code == "MOTHERBOARD_EXPIRED" || problem.Code == "PROCESSOR_BANNED" || problem.Code == "PROCESSOR_PAUSED" || problem.Code == "PROCESSOR_EXPIRED") { c.invalidate(context.Background(), problem) } return Result{}, last } } c.connection("disconnected") if budget.Err() != nil { return Result{}, failure("NETWORK_TIMEOUT", "The request timed out. Try again when connected.", "network") } until, _ := budget.Deadline() if !retry || attempt == 2 || delay < 0 || time.Until(until) < delay+50*time.Millisecond { return Result{}, last } select { case <-time.After(delay): case <-budget.Done(): if ctx.Err() != nil { return Result{}, ctx.Err() } return Result{}, failure("NETWORK_TIMEOUT", "The request timed out.", "network") } } return Result{}, last } func (c *AuthlyX) Initialize(ctx context.Context) (Result, error) { return c.Init(ctx) } func (c *AuthlyX) InitializeAsync(ctx context.Context, callback func(Result)) error { return c.InitAsync(ctx, callback) } func (c *AuthlyX) Init(ctx context.Context) (Result, error) { if e := c.lock(ctx); e != nil { return Result{}, e } defer c.unlock() return c.request(ctx, "/v3/initialize", object(text("appKey", c.o.AppKey), text("version", c.o.Version)), false, true) } func (c *AuthlyX) UserData(ctx context.Context) (map[string]any, error) { if e := c.lock(ctx); e != nil { return nil, e } defer c.unlock() encoded, e := json.Marshal(c.userData) if e != nil { return nil, e } var data map[string]any e = json.Unmarshal(encoded, &data) return data, e } func (c *AuthlyX) RegisterUser(ctx context.Context, username, password, licenseKey string) (Result, error) { return c.login(ctx, "register", username, password, licenseKey) } func (c *AuthlyX) ChangePassword(ctx context.Context, currentPassword, newPassword string) (Result, error) { return c.protected(ctx, "/v3/account/password", object(text("currentPassword", currentPassword), text("newPassword", newPassword)), false) } func (c *AuthlyX) RedeemLicense(ctx context.Context, licenseKey string) (Result, error) { return c.protected(ctx, "/v3/licenses/redeem", object(text("licenseKey", licenseKey)), false) } func (c *AuthlyX) Log(ctx context.Context, message string) (Result, error) { return c.protected(ctx, "/v3/logs/add", object(text("message", message)), false) } func (c *AuthlyX) Login(ctx context.Context, username, password string) (Result, error) { return c.login(ctx, "user", username, password, "") } func (c *AuthlyX) LicenseLogin(ctx context.Context, license string) (Result, error) { return c.login(ctx, "license", "", "", license) } func (c *AuthlyX) DeviceLogin(ctx context.Context) (Result, error) { return c.login(ctx, "device", "", "", "") } func (c *AuthlyX) login(ctx context.Context, kind, username, password, license string) (Result, error) { if !utf8.ValidString(username) || !utf8.ValidString(password) { return Result{}, errors.New("credentials must be valid UTF-8") } if e := c.lock(ctx); e != nil { return Result{}, e } defer c.unlock() if c.token != "" { return Result{}, failure("ALREADY_SIGNED_IN", "Sign out before starting another session.", "server") } if e := c.clearOffline(ctx); e != nil { return Result{}, e } c.loggingOut = false challenge, e := c.request(ctx, "/v3/challenge", object(text("appKey", c.o.AppKey), text("installationPublicKey", c.publicPEM)), false, false) if e != nil { return Result{}, e } payload := stringValue(challenge.Data["payload"]) operation := object(text("type", kind), text("appKey", c.o.AppKey), text("version", c.o.Version), text("sid", c.o.SystemID), text("hash", c.o.BuildHash), text("username", username), text("password", password), text("licenseKey", license)) proof := object(text("challenge", payload), pair{"operation", operation}) signature := base64.StdEncoding.EncodeToString(ed25519.Sign(c.key, []byte(proof))) body := strings.TrimSuffix(operation, "}") + "," + quote("challengeId") + ":" + quote(stringValue(challenge.Data["challengeId"])) + "," + quote("signature") + ":" + quote(signature) + "}" result, e := c.request(ctx, "/v3/login", body, false, false) if e != nil { return Result{}, e } claims, e := decode([]byte(payload)) if e != nil { return Result{}, e } c.appID = stringValue(claims["appId"]) c.token = stringValue(result.Data["token"]) c.sessionID = stringValue(result.Data["sessionId"]) c.identityID = stringValue(result.Data["identityId"]) c.userData = result.Data["identity"].(map[string]any) for dest, src := range map[string]string{"SID": "systemId", "Email": "email", "Plan": "plan", "ExpiryDate": "expiry", "Country": "country", "IpAddress": "ipAddress", "DeviceLimit": "deviceLimit", "LicenseKey": "licenseKey"} { c.userData[dest] = c.userData[src] } if c.userData["type"] == "user" { c.userData["Username"] = c.userData["name"] } if e = c.lease(result.Data); e != nil { c.invalidate(context.Background(), failure("LEASE_INVALID", "The session deadline is invalid.", "security")) return Result{}, e } delete(result.Data, "token") c.startHeartbeat() return result, nil } func (c *AuthlyX) lease(data map[string]any) error { t, e := time.Parse(time.RFC3339Nano, stringValue(data["accessDeadline"])) if e != nil || t.UnixMilli() > c.now()+7200100 { e := failure("LEASE_INVALID", "The session deadline is invalid.", "security") c.invalidate(context.Background(), e) return e } c.deadline = t.UnixMilli() if c.userData == nil { c.userData = make(map[string]any) } for _, key := range []string{"features", "featureValues", "metadata"} { if value, exists := data[key]; exists { c.userData[key] = value } } if v := number(data["heartbeatSeconds"]); v >= 1 && v <= 3600 { c.heartbeatSeconds = v } if v := number(data["jitterSeconds"]); v >= 0 && v <= 15 { c.jitterSeconds = v } return nil } func (c *AuthlyX) CheckSession(ctx context.Context) (Result, error) { if e := c.lock(ctx); e != nil { return Result{}, e } defer c.unlock() r, e := c.request(ctx, "/v3/session/check", "{}", true, true) if e == nil { e = c.lease(r.Data) } return r, e } func (c *AuthlyX) protected(ctx context.Context, path, body string, retry bool) (Result, error) { if e := c.lock(ctx); e != nil { return Result{}, e } defer c.unlock() if c.token != "" && c.now() >= c.deadline { r, e := c.request(ctx, "/v3/session/check", "{}", true, true) if e != nil { return Result{}, e } if e = c.lease(r.Data); e != nil { return Result{}, e } } return c.request(ctx, path, body, true, retry) } func (r Result) OK() bool { return r.Success } func (r Result) Failed() bool { return !r.Success } func (c *AuthlyX) complete(operation func() (Result, error), callback func(Result)) error { if callback == nil { return errors.New("a completion callback is required") } go func() { result, problem := operation() if problem != nil { result.Success = false result.Message = problem.Error() result.Code = "CLIENT_ERROR" var sdkError *Error if errors.As(problem, &sdkError) { result.Code, result.Message, result.RequestID = sdkError.Code, sdkError.Message, sdkError.RequestID } } callback(result) }() return nil } func (c *AuthlyX) InitAsync(ctx context.Context, callback func(Result)) error { return c.complete(func() (Result, error) { return c.Init(ctx) }, callback) } func (c *AuthlyX) LicenseLoginAsync(ctx context.Context, key string, callback func(Result)) error { return c.complete(func() (Result, error) { return c.LicenseLogin(ctx, key) }, callback) } func (c *AuthlyX) LoginAsync(ctx context.Context, username, password string, callback func(Result)) error { return c.complete(func() (Result, error) { return c.Login(ctx, username, password) }, callback) } func (c *AuthlyX) GetVariableAsync(ctx context.Context, name string, callback func(Result)) error { return c.complete(func() (Result, error) { return c.GetVariable(ctx, name) }, callback) } func (c *AuthlyX) GetScriptAsync(ctx context.Context, name string, revision int, callback func(Result)) error { return c.complete(func() (Result, error) { return c.GetScript(ctx, name, revision) }, callback) } func (c *AuthlyX) GetMetadata(ctx context.Context, key ...string) (Result, error) { if len(key) > 0 { return c.protected(ctx, "/v3/metadata/get", object(text("key", key[0])), true) } return c.protected(ctx, "/v3/metadata/get", object(), true) } func (c *AuthlyX) UpdateVariable(ctx context.Context, name, value string) (Result, error) { return c.protected(ctx, "/v3/data/set", object(text("name", name), text("value", value)), false) } func (c *AuthlyX) GetFeatures(ctx context.Context) (Result, error) { return c.protected(ctx, "/v3/features/list", object(), true) } func (c *AuthlyX) GetFeature(ctx context.Context, name string) (Result, error) { return c.protected(ctx, "/v3/features/get", object(text("name", name)), true) } func (c *AuthlyX) GetAllMetadata(ctx context.Context) (Result, error) { return c.protected(ctx, "/v3/metadata/list", object(), true) } func (c *AuthlyX) CheckMetadata(ctx context.Context, key string) (Result, error) { return c.protected(ctx, "/v3/metadata/check", object(text("key", key)), true) } func (c *AuthlyX) SendWebhook(ctx context.Context, name string, data any) (Result, error) { encoded, err := json.Marshal(data) if err != nil { return Result{}, err } return c.protected(ctx, "/v3/webhooks/send", object(text("event", name), pair{"data", string(encoded)}), false) } func (c *AuthlyX) SetMetadata(ctx context.Context, key string, value any) (Result, error) { encoded, err := json.Marshal(value) if err != nil { return Result{}, err } return c.protected(ctx, "/v3/metadata/set", object(text("key", key), pair{"value", string(encoded)}), false) } func (c *AuthlyX) CheckFeature(ctx context.Context, name string) (Result, error) { return c.protected(ctx, "/v3/features/check", object(text("name", name)), true) } func (c *AuthlyX) GetVariable(ctx context.Context, name string) (Result, error) { return c.protected(ctx, "/v3/data/get", object(text("name", name)), true) } func (c *AuthlyX) GetScript(ctx context.Context, name string, revision int) (Result, error) { fields := []pair{text("name", name)} if revision > 0 { fields = append(fields, pair{"revision", strconv.Itoa(revision)}) } r, e := c.protected(ctx, "/v3/scripts/get", object(fields...), true) if e != nil { return r, e } payload := stringValue(r.Data["signedPayload"]) m, e := decode([]byte(payload)) if e == nil { _, hasIssued := m["issuedAt"] _, hasExpires := m["expiresAt"] if hasIssued || hasExpires { issued, expires := number(m["issuedAt"]), number(m["expiresAt"]) if !hasIssued || !hasExpires || issued <= 0 || issued > float64(c.now()+30000) || expires <= float64(c.now()) || expires <= issued { return Result{}, failure("SCRIPT_INVALID", "The script could not be verified.", "security") } } if minimum, exists := m["minimumRevision"]; exists && (number(minimum) < 1 || number(m["revision"]) < number(minimum)) { return Result{}, failure("SCRIPT_INVALID", "The script could not be verified.", "security") } } content := stringValue(r.Data["content"]) if e != nil || !verifySignature(c.o.ScriptKeys[stringValue(m["keyId"])], payload, stringValue(r.Data["signature"])) || !reflect.DeepEqual(m, r.Data["manifest"]) || m["appId"] != c.appID || m["name"] != name || (revision > 0 && int(number(m["revision"])) != revision) || m["sha256"] != hash([]byte(content)) || int(number(m["bytes"])) != len([]byte(content)) { return Result{}, failure("SCRIPT_INVALID", "The script could not be verified.", "security") } return r, nil } func (c *AuthlyX) SaveOfflineAccess(ctx context.Context) (Result, error) { if e := c.lock(ctx); e != nil { return Result{}, e } defer c.unlock() challenge, e := c.request(ctx, "/v3/offline/challenge", "{}", true, false) if e != nil { return Result{}, e } proof := object(text("challenge", stringValue(challenge.Data["payload"])), pair{"operation", object(text("action", "offlinePermit"), text("sessionId", c.sessionID))}) signature := base64.StdEncoding.EncodeToString(ed25519.Sign(c.key, []byte(proof))) r, e := c.request(ctx, "/v3/offline/permit", object(text("challengeId", stringValue(challenge.Data["challengeId"])), text("signature", signature)), true, false) if e != nil { return r, e } c.offline = &offlineState{AppID: c.appID, IdentityID: c.identityID, Permit: map[string]string{"signedPayload": stringValue(r.Data["signedPayload"]), "signature": stringValue(r.Data["signature"])}, TrustedTime: c.now(), LocalTime: time.Now().UnixMilli()} if !c.validOffline() { _ = c.clearOffline(context.Background()) return Result{}, failure("OFFLINE_INVALID", "The offline permit could not be verified.", "security") } return r, c.persist(ctx) } func (c *AuthlyX) validOffline() bool { if c.offline == nil || c.disposed || c.loggingOut || time.Now().UnixMilli() < c.wallTime { return false } p := c.offline.Permit v, e := decode([]byte(p["signedPayload"])) if e != nil || len(p["signedPayload"]) > 4096 { return false } id := stringValue(v["keyId"]) pub, e := publicKey(c.o.OfflineKeys[id]) if e != nil || fingerprint(pub) != id || !verifySignature(c.o.OfflineKeys[id], p["signedPayload"], p["signature"]) { return false } issued, expires := int64(number(v["issuedAt"])), int64(number(v["expiresAt"])) now := c.now() return v["type"] == "authlyx.offline.v1" && v["appId"] == c.appID && v["subjectId"] == c.identityID && v["installationKeyHash"] == c.installationHash && issued <= now && now < expires && expires > issued && expires-issued <= 2592000000 && now >= c.offline.TrustedTime } func (c *AuthlyX) persist(ctx context.Context) error { c.offline.TrustedTime = c.now() c.offline.LocalTime = time.Now().UnixMilli() b, e := json.Marshal(c.offline) if e == nil { e = c.o.Storage.Save(ctx, c.prefix+".offline", string(b)) } return e } func (c *AuthlyX) HasOfflineAccess(ctx context.Context) bool { if c.lock(ctx) != nil { return false } defer c.unlock() if !c.validOffline() { return false } if c.persist(ctx) != nil { c.offline = nil return false } return true } func (c *AuthlyX) HasAccess(ctx context.Context) bool { if c.lock(ctx) != nil { return false } defer c.unlock() if c.loggingOut { return false } if c.token != "" && c.deadline > c.now() { return true } if !c.validOffline() { return false } if c.persist(ctx) != nil { c.offline = nil return false } return true } func (c *AuthlyX) Logout(ctx context.Context) error { if e := c.lock(context.Background()); e != nil { return e } defer c.unlock() c.loggingOut = true c.stopHeartbeat() var e error if c.token != "" { _, e = c.request(ctx, "/v3/session/logout", "{}", true, false) } c.token = "" c.userData = nil c.deadline = 0 clear := c.clearOffline(context.Background()) if e != nil { return e } return clear } func (c *AuthlyX) stopHeartbeat() { if c.heartbeatCancel != nil { c.heartbeatCancel() c.heartbeatCancel = nil } } func (c *AuthlyX) startHeartbeat() { c.stopHeartbeat() if c.o.ManualHeartbeat { return } ctx, cancel := context.WithCancel(c.life) c.heartbeatCancel = cancel go func() { for { if c.lock(ctx) != nil { return } duration := time.Duration((c.heartbeatSeconds + (float64(binary.LittleEndian.Uint32(random(4)))/float64(^uint32(0))*2-1)*c.jitterSeconds) * float64(time.Second)) active := c.token != "" c.unlock() if !active { return } if duration < time.Second { duration = time.Second } select { case <-time.After(duration): case <-ctx.Done(): return } _, _ = c.CheckSession(ctx) } }() } func (c *AuthlyX) OnResume(ctx context.Context) (Result, error) { return c.CheckSession(ctx) } func (c *AuthlyX) Close() { c.cancel() c.gate <- struct{}{} defer c.unlock() if c.disposed { return } c.disposed = true c.stopHeartbeat() c.token = "" c.userData = nil c.deadline = 0 for i := range c.key { c.key[i] = 0 } c.http.CloseIdleConnections() } type Client = AuthlyX func SystemID() (string, error) { if runtime.GOOS != "windows" { return "", errors.New("supply a platform system ID through Options") } ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) defer cancel() output, err := exec.CommandContext(ctx, filepath.Join(os.Getenv("SystemRoot"), "System32", "whoami.exe"), "/user", "/fo", "csv", "/nh").Output() if err != nil { return "", err } sid := regexp.MustCompile(`S-1-\d+(?:-\d+)+`).FindString(string(output)) if sid == "" { return "", errors.New("could not read the Windows user SID") } return sid, nil } func DefaultOptions(appKey, version string) (Options, error) { sid, err := SystemID() if err != nil { return Options{}, err } if os.Getenv("LOCALAPPDATA") == "" { return Options{}, errors.New("LOCALAPPDATA is unavailable") } store, err := NewWindowsProtectedStore(filepath.Join(os.Getenv("LOCALAPPDATA"), "AuthlyX", "v3")) if err != nil { return Options{}, err } return Options{AppKey: appKey, Version: version, SystemID: sid, Endpoint: "https://api.authlyx.dev", AllowLocalHTTP: true, Storage: store, ResponseKeys: map[string]string{"2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n"}, OfflineKeys: map[string]string{"d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n"}, ScriptKeys: map[string]string{"5aec455eb0b10697": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n"}, }, nil } func NewAuthlyX(ctx context.Context, appKey, version string) (*AuthlyX, error) { options, err := DefaultOptions(appKey, version) if err != nil { return nil, err } return New(ctx, options) } ``` # Complete Rust V3 SDK source ```rust // AuthlyX Rust SDK Version 3.0 BETA #![allow(non_snake_case)] use base64::{engine::general_purpose::STANDARD as B64, Engine}; use ed25519_dalek::{ pkcs8::{spki::der::pem::LineEnding, DecodePublicKey, EncodePublicKey}, Signature, Signer, SigningKey, Verifier, VerifyingKey, }; use rand::RngCore; use serde::{Deserialize, Serialize}; use serde_json::{json, Value}; use sha2::{Digest, Sha256}; use std::{ collections::HashMap, sync::{Arc, Mutex as StdMutex}, time::{Duration, Instant, SystemTime, UNIX_EPOCH}, }; use storage::ProtectedStore; use tokio::sync::{broadcast, Mutex}; use tokio_util::sync::CancellationToken; #[derive(Clone, Debug)] pub struct Error { pub code: String, pub message: String, pub kind: &'static str, pub status: u16, pub request_id: Option, } impl std::fmt::Display for Error { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "{}: {}", self.code, self.message) } } impl std::error::Error for Error {} fn err(code: &str, message: &str, kind: &'static str) -> Error { Error { code: code.into(), message: message.into(), kind, status: 0, request_id: None, } } #[derive(Clone, Deserialize)] pub struct Response { pub success: bool, pub code: String, pub message: String, pub data: Value, #[serde(rename = "requestId")] pub request_id: String, } impl Response { pub fn ok(&self) -> bool { self.success } pub fn failed(&self) -> bool { !self.success } pub fn decode(&self) -> Result { serde_json::from_value(self.data.clone()).map_err(|_| { err( "DATA_INVALID", "The response data could not be decoded.", "security", ) }) } } #[derive(Clone, Debug)] pub enum Event { Connection(&'static str), SessionInvalidated(Error), } #[derive(Clone)] pub struct Options { pub app_key: String, pub version: String, pub systemId: String, pub endpoint: String, pub response_keys: HashMap, pub offline_keys: HashMap, pub script_keys: HashMap, pub storage: Arc, pub build_hash: String, pub request_budget: Duration, pub manual_heartbeat: bool, pub allow_local_http: bool, } impl Options { pub fn withHeartbeat(mut self, mode: &str) -> Result { self.manual_heartbeat = match mode { "server" => false, "manual" => true, _ => { return Err(err( "CONFIG_INVALID", "Use server or manual heartbeat mode.", "storage", )) } }; Ok(self) } } #[derive(Clone, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] struct Offline { app_id: String, identity_id: String, permit: Value, trusted_time: i64, local_time: i64, } struct State { token: Option, session_id: String, app_id: String, identity_id: String, offline: Option, anchor_server: i64, anchor_mono: Instant, anchor_wall: i64, deadline: i64, heartbeat_seconds: f64, jitter_seconds: f64, logging_out: bool, } impl State { fn anchor(&mut self, value: i64) { self.anchor_server = value; self.anchor_mono = Instant::now(); self.anchor_wall = wall() } fn now(&self) -> i64 { if self.anchor_server == 0 { wall() } else { self.anchor_server + self.anchor_mono.elapsed().as_millis() as i64 } } } struct Inner { o: Options, http: reqwest::Client, key: SigningKey, public_pem: String, key_hash: String, prefix: String, userData: StdMutex, state: Mutex, life: CancellationToken, heartbeat: StdMutex>, events: broadcast::Sender, } impl Drop for Inner { fn drop(&mut self) { self.life.cancel(); } } #[derive(Clone)] pub struct AuthlyX { inner: Arc, } fn wall() -> i64 { SystemTime::now() .duration_since(UNIX_EPOCH) .unwrap_or_default() .as_millis() as i64 } fn hash(value: impl AsRef<[u8]>) -> String { Sha256::digest(value.as_ref()) .iter() .map(|b| format!("{b:02x}")) .collect() } fn text<'a>(value: &'a Value, key: &str) -> &'a str { value.get(key).and_then(Value::as_str).unwrap_or("") } fn timestamp(value: &str) -> Result { chrono::DateTime::parse_from_rfc3339(value) .map(|v| v.timestamp_millis()) .map_err(|_| { err( "RESPONSE_INVALID", "The server timestamp is invalid.", "security", ) }) } fn verify(pem: &str, payload: &str, signature: &str) -> bool { let Ok(key) = VerifyingKey::from_public_key_pem(pem) else { return false; }; let Ok(bytes) = B64.decode(signature) else { return false; }; let Ok(sig) = Signature::from_slice(&bytes) else { return false; }; key.verify(payload.as_bytes(), &sig).is_ok() } fn fingerprint(pem: &str) -> Option { let k = VerifyingKey::from_public_key_pem(pem).ok()?; Some(hash(k.to_public_key_der().ok()?.as_bytes())) } pub type Client = AuthlyX; impl AuthlyX { pub fn systemId() -> Result { if !cfg!(windows) { return Err(err( "SYSTEM_ID_UNAVAILABLE", "Supply a platform system ID through Options.", "storage", )); } let system = std::env::var("SystemRoot").map_err(|_| { err( "SYSTEM_ID_UNAVAILABLE", "SystemRoot is unavailable.", "storage", ) })?; let output = std::process::Command::new(std::path::Path::new(&system).join("System32/whoami.exe")) .args(["/user", "/fo", "csv", "/nh"]) .output() .map_err(|_| { err( "SYSTEM_ID_UNAVAILABLE", "Could not read the Windows user SID.", "storage", ) })?; let value = String::from_utf8_lossy(&output.stdout); let sid = value.split('"').find(|part| { part.starts_with("S-1-") && part .chars() .all(|c| c.is_ascii_digit() || c == 'S' || c == '-') }); match sid { Some(sid) if output.status.success() => Ok(sid.to_owned()), _ => Err(err( "SYSTEM_ID_UNAVAILABLE", "Could not read the Windows user SID.", "storage", )), } } pub fn defaults(app_key: &str, version: &str) -> Result { let directory = std::env::var("LOCALAPPDATA").map_err(|_| { err( "STORAGE_UNAVAILABLE", "LOCALAPPDATA is unavailable.", "storage", ) })?; Ok(Options {app_key: app_key.into(), version: version.into(), systemId: Self::systemId()?, endpoint: "https://api.authlyx.dev".into(), allow_local_http: true, storage: Arc::new(storage::WindowsProtectedStore::new(std::path::Path::new(&directory).join("AuthlyX/v3"))?), build_hash: String::new(), request_budget: Duration::from_secs(8), manual_heartbeat: false, response_keys: HashMap::from([("2318305346828e7b61e0447bfc4b3daac50dcda1b425814120ee3d6947609052".into(), "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaXXIKXRn0uPJ16wc4SX1GLArAGTAPeVhreGxp4f9/6Q=\n-----END PUBLIC KEY-----\n".into())]), offline_keys: HashMap::from([("d3ea94e9f098eece181306689713c9f4d984c0321948fbd0007ef471bcf5b7d2".into(), "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA7d2GrJ8SIUFor6bZuXo0NCX2k9SkHVz5PxOZDut3ydk=\n-----END PUBLIC KEY-----\n".into())]), script_keys: HashMap::from([("5aec455eb0b10697".into(), "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0zpUhvFdbX95R1Q0+105MZsJr0IJ/yFTNxSiUwqfFH0=\n-----END PUBLIC KEY-----\n".into())]), }) } pub async fn new(app_key: &str, version: &str) -> Result { Self::withOptions(Self::defaults(app_key, version)?).await } pub async fn withOptions(mut o: Options) -> Result { let url = url::Url::parse(&o.endpoint) .map_err(|_| err("CONFIG_INVALID", "Invalid API origin.", "storage"))?; let local = matches!( url.host_str(), Some("localhost" | "127.0.0.1" | "[::1]" | "::1") ); if url.path() != "/" || url.query().is_some() || url.fragment().is_some() || !url.username().is_empty() || url.password().is_some() || (url.scheme() != "https" && !(o.allow_local_http && url.scheme() == "http" && local)) { return Err(err( "CONFIG_INVALID", "Use an HTTPS API origin; HTTP is limited to explicit loopback testing.", "storage", )); } if o.app_key.is_empty() || o.version.is_empty() || o.systemId.is_empty() || o.response_keys.is_empty() || o.request_budget < Duration::from_millis(100) || o.request_budget > Duration::from_secs(60) { return Err(err("CONFIG_INVALID","Provide app identity, protected storage, trusted keys and a bounded request budget.","storage")); } o.endpoint = url.origin().ascii_serialization(); let prefix = format!( "authlyx.v3.{}", hash(format!("{}/\n{}\n{}", o.endpoint, o.app_key, o.systemId)) ); let identity_name = format!( "authlyx.v3.installation.{}", hash(format!("{}/\n{}", o.endpoint, o.systemId)) ); let saved = o.storage.load(&identity_name).await?; let mut seed = [0u8; 32]; if let Some(value) = saved { let bytes = B64.decode(value).map_err(|_| { err( "STORAGE_INVALID", "Invalid protected installation key.", "storage", ) })?; if bytes.len() != 32 { return Err(err( "STORAGE_INVALID", "Invalid protected installation key.", "storage", )); }; seed.copy_from_slice(&bytes) } else { rand::rngs::OsRng.fill_bytes(&mut seed); o.storage.save(&identity_name, &B64.encode(seed)).await? } let key = SigningKey::from_bytes(&seed); seed.fill(0); let public_pem = key .verifying_key() .to_public_key_pem(LineEnding::LF) .map_err(|_| { err( "KEY_INVALID", "Could not export installation key.", "security", ) })?; let key_hash = fingerprint(&public_pem).unwrap(); let mut state = State { token: None, session_id: String::new(), app_id: String::new(), identity_id: String::new(), offline: None, anchor_server: 0, anchor_mono: Instant::now(), anchor_wall: 0, deadline: 0, heartbeat_seconds: 600.0, jitter_seconds: 15.0, logging_out: false, }; if let Some(saved) = o.storage.load(&(prefix.clone() + ".offline")).await? { let offline: Offline = serde_json::from_str(&saved).map_err(|_| { err( "STORAGE_INVALID", "Invalid protected offline state.", "storage", ) })?; if wall() < offline.local_time { return Err(err( "STORAGE_INVALID", "The local clock moved backwards.", "storage", )); }; state.app_id = offline.app_id.clone(); state.identity_id = offline.identity_id.clone(); state.anchor(offline.trusted_time + wall() - offline.local_time); state.offline = Some(offline) } let http = reqwest::Client::builder() .redirect(reqwest::redirect::Policy::none()) .build() .map_err(|_| { err( "CONFIG_INVALID", "Could not create the HTTPS client.", "network", ) })?; let (events, _) = broadcast::channel(32); let client = Self { inner: Arc::new(Inner { o, http, key, public_pem, key_hash, prefix, userData: StdMutex::new(json!({})), state: Mutex::new(state), life: CancellationToken::new(), heartbeat: StdMutex::new(None), events, }), }; { let mut state = client.inner.state.lock().await; if state.offline.is_some() && !client.valid_offline(&state) { client.clear_offline(&mut state).await? } } Ok(client) } pub fn subscribe(&self) -> broadcast::Receiver { self.inner.events.subscribe() } fn sign(&self, payload: &str) -> String { B64.encode(self.inner.key.sign(payload.as_bytes()).to_bytes()) } fn stop_heartbeat(&self) { if let Some(cancel) = self.inner.heartbeat.lock().unwrap().take() { cancel.cancel() } } async fn clear_offline(&self, s: &mut State) -> Result<(), Error> { s.offline = None; self.inner .o .storage .delete(&(self.inner.prefix.clone() + ".offline")) .await } async fn invalidate(&self, s: &mut State, e: Error) { s.token = None; *self.inner.userData.lock().unwrap() = json!({}); s.deadline = 0; self.stop_heartbeat(); let _ = self.clear_offline(s).await; let _ = self.inner.events.send(Event::SessionInvalidated(e)); } fn verify_response( &self, s: &mut State, outer: &Value, status: u16, path: &str, body: &str, nonce: &str, ) -> Result { let invalid = || { err( "RESPONSE_INVALID", "The server response could not be verified.", "security", ) }; let proof = &outer["verification"]; let id = text(proof, "keyId"); let pem = self.inner.o.response_keys.get(id).ok_or_else(invalid)?; let payload = text(proof, "signedPayload"); if payload.len() > 2000000 || fingerprint(pem).as_deref() != Some(id) || !verify(pem, payload, text(proof, "signature")) { return Err(invalid()); } let signed: Value = serde_json::from_str(payload).map_err(|_| invalid())?; let mut envelope = outer.clone(); envelope .as_object_mut() .ok_or_else(invalid)? .remove("verification"); if signed["type"] != "authlyx.response.v3" || signed["keyId"] != id || signed["httpStatus"] != status || signed["request"] != json!({"method":"POST","path":path,"nonce":nonce,"bodySha256":hash(body)}) || signed["response"] != envelope { return Err(invalid()); } let result: Response = serde_json::from_value(envelope).map_err(|_| invalid())?; if result.code.is_empty() || result.request_id.is_empty() { return Err(invalid()); } s.anchor(timestamp(text(&signed, "serverTime"))?); Ok(result) } async fn request( &self, s: &mut State, path: &str, data: Value, auth: bool, retry: bool, ) -> Result { if self.inner.life.is_cancelled() { return Err(err("DISPOSED", "This client is disposed.", "cancelled")); } if auth && s.token.is_none() { return Err(err( "NOT_SIGNED_IN", "Sign in before using this feature.", "server", )); } let body = data.to_string(); let until = tokio::time::Instant::now() + self.inner.o.request_budget; let work = async { for attempt in 0..3 { let mut bytes = [0u8; 24]; rand::rngs::OsRng.fill_bytes(&mut bytes); let nonce = bytes.iter().map(|b| format!("{b:02x}")).collect::(); let stamp = s.now().to_string(); let mut request = self .inner .http .post(format!("{}{}", self.inner.o.endpoint, path)) .header("Content-Type", "application/json") .header("X-AuthlyX-Nonce", &nonce) .body(body.clone()); if let Some(token) = s.token.as_ref().filter(|_| auth) { let proof = json!({"type":"authlyx.request.v3","method":"POST","path":path,"bodySha256":hash(&body),"nonce":nonce,"timestamp":stamp,"tokenHash":hash(token)}); request = request .bearer_auth(token) .header("X-AuthlyX-Timestamp", &stamp) .header("X-AuthlyX-Signature", self.sign(&proof.to_string())) } let mut delay = Duration::from_millis(150); let result = match request.send().await { Err(_) => Err(err( "NETWORK_ERROR", "Could not connect to AuthlyX.", "network", )), Ok(mut response) => { let status = response.status().as_u16(); if let Some(after) = response .headers() .get("Retry-After") .and_then(|v| v.to_str().ok()) { delay = after .parse::() .ok() .map(Duration::from_secs) .or_else(|| { chrono::DateTime::parse_from_rfc2822(after).ok().map(|v| { Duration::from_millis( v.timestamp_millis().saturating_sub(wall()).max(0) as u64, ) }) }) .unwrap_or(self.inner.o.request_budget) } let mut raw = Vec::new(); let mut read_error = false; while let Some(chunk) = response.chunk().await.map_err(|_| { err( "NETWORK_ERROR", "Could not read the server response.", "network", ) })? { raw.extend_from_slice(&chunk); if raw.len() > 2000000 { read_error = true; break; } } if read_error { Err(err( "RESPONSE_INVALID", "The server response is too large.", "security", )) } else { let outer = serde_json::from_slice::(&raw); match outer { Err(_) if status >= 500 => Err(err( "SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network", )), Err(_) => Err(err( "RESPONSE_INVALID", "The server response is not valid JSON.", "security", )), Ok(value) if value.get("verification").is_none() && status >= 500 => { Err(err( "SERVICE_UNAVAILABLE", "The service is temporarily unavailable.", "network", )) } Ok(value) => self .verify_response(s, &value, status, path, &body, &nonce) .and_then(|r| { if status >= 400 || !r.success { Err(Error { code: r.code, message: r.message, kind: if status == 429 || status >= 500 { "network" } else { "server" }, status, request_id: Some(r.request_id), }) } else { Ok(r) } }), } } } }; match result { Ok(value) => { let _ = self.inner.events.send(Event::Connection("online")); return Ok(value); } Err(e) => { if retry && attempt < 2 && (e.kind == "network" || e.code == "REQUEST_TIME_INVALID") && tokio::time::Instant::now() + delay + Duration::from_millis(50) < until { tokio::time::sleep(delay).await; continue; } return Err(e); } } } Err(err( "NETWORK_ERROR", "Could not connect to AuthlyX.", "network", )) }; let result = tokio::select! {_ = self.inner.life.cancelled()=>Err(err("REQUEST_CANCELLED","The request was cancelled.","cancelled")),value=tokio::time::timeout_at(until,work)=>value.unwrap_or_else(|_|Err(err("NETWORK_TIMEOUT","The request timed out. Try again when connected.","network")))}; if let Err(e) = &result { if e.kind == "security" { let _ = self.inner.events.send(Event::Connection("untrusted")); self.invalidate(s, e.clone()).await } else if e.kind == "network" { let _ = self.inner.events.send(Event::Connection("disconnected")); } else if auth && matches!( e.code.as_str(), "SESSION_EXPIRED" | "ACCESS_REVOKED" | "APP_PAUSED" | "ACCESS_EXPIRED" | "ACCESS_DENIED" | "IP_BLACKLISTED" | "IP_NOT_WHITELISTED" | "SID_BLACKLISTED" | "SID_NOT_WHITELISTED" | "VERSION_NOT_ALLOWED" | "HASH_NOT_ALLOWED" | "COUNTRY_BLOCKED" | "VPN_NOT_ALLOWED" | "DEVICE_NOT_ALLOWED" | "APP_DISABLED" | "IP_BLOCKED" | "SID_BLOCKED" | "UPDATE_REQUIRED" | "INVALID_HASH" | "VPN_BLOCKED" | "USER_BANNED" | "USER_SUSPENDED" | "USER_EXPIRED" | "LICENSE_BANNED" | "LICENSE_PAUSED" | "LICENSE_EXPIRED" | "MOTHERBOARD_BANNED" | "MOTHERBOARD_PAUSED" | "MOTHERBOARD_EXPIRED" | "PROCESSOR_BANNED" | "PROCESSOR_PAUSED" | "PROCESSOR_EXPIRED" ) { self.invalidate(s, e.clone()).await } } result } pub async fn initialize(&self) -> Result { self.init().await } pub fn initializeWith(&self, completed: F) -> tokio::task::JoinHandle<()> where F: FnOnce(Result) + Send + 'static, { self.initWith(completed) } pub async fn init(&self) -> Result { let mut s = self.inner.state.lock().await; self.request( &mut s, "/v3/initialize", json!({"appKey":self.inner.o.app_key,"version":self.inner.o.version}), false, true, ) .await } pub fn userData(&self) -> Value { self.inner.userData.lock().unwrap().clone() } pub async fn registerUser( &self, username: &str, password: &str, license_key: &str, ) -> Result { self.login_impl("register", username, password, license_key) .await } pub async fn changePassword( &self, current_password: &str, new_password: &str, ) -> Result { self.protected( "/v3/account/password", json!({"currentPassword":current_password,"newPassword":new_password}), false, ) .await } pub async fn redeemLicense(&self, license_key: &str) -> Result { self.protected( "/v3/licenses/redeem", json!({"licenseKey":license_key}), false, ) .await } pub async fn log(&self, message: &str) -> Result { self.protected("/v3/logs/add", json!({"message":message}), false) .await } pub async fn login(&self, username: &str, password: &str) -> Result { self.login_impl("user", username, password, "").await } pub async fn licenseLogin(&self, license: &str) -> Result { self.login_impl("license", "", "", license).await } pub async fn deviceLogin(&self) -> Result { self.login_impl("device", "", "", "").await } async fn login_impl( &self, kind: &str, username: &str, password: &str, license: &str, ) -> Result { let mut s = self.inner.state.lock().await; if s.token.is_some() { return Err(err( "ALREADY_SIGNED_IN", "Sign out before starting another session.", "server", )); } self.clear_offline(&mut s).await?; s.logging_out = false; let challenge=self.request(&mut s,"/v3/challenge",json!({"appKey":self.inner.o.app_key,"installationPublicKey":self.inner.public_pem}),false,false).await?.data; let operation = json!({"type":kind,"appKey":self.inner.o.app_key,"version":self.inner.o.version,"sid":self.inner.o.systemId,"hash":self.inner.o.build_hash,"username":username,"password":password,"licenseKey":license}); let signature = self.sign(&json!({"challenge":challenge["payload"],"operation":operation}).to_string()); let mut body = operation; body["challengeId"] = challenge["challengeId"].clone(); body["signature"] = signature.into(); let mut result = self .request(&mut s, "/v3/login", body, false, false) .await?; s.app_id = text( &serde_json::from_str::(text(&challenge, "payload")) .map_err(|_| err("RESPONSE_INVALID", "Invalid challenge.", "security"))?, "appId", ) .into(); let mut identity = result.data["identity"].clone(); for (dest, src) in [ ("SID", "systemId"), ("Email", "email"), ("Plan", "plan"), ("ExpiryDate", "expiry"), ("Country", "country"), ("IpAddress", "ipAddress"), ("DeviceLimit", "deviceLimit"), ("LicenseKey", "licenseKey"), ] { identity[dest] = identity[src].clone(); } identity["Username"] = if identity["type"] == "user" { identity["name"].clone() } else { json!("") }; *self.inner.userData.lock().unwrap() = identity; s.identity_id = text(&result.data, "identityId").into(); s.session_id = text(&result.data, "sessionId").into(); s.token = Some(text(&result.data, "token").into()); self.lease(&mut s, &result.data).await?; result.data.as_object_mut().unwrap().remove("token"); drop(s); self.start_heartbeat(); Ok(result) } async fn lease(&self, s: &mut State, data: &Value) -> Result<(), Error> { let deadline = timestamp(text(data, "accessDeadline")).unwrap_or(0); if deadline <= 0 || deadline > s.now() + 7200100 { let error = err( "LEASE_INVALID", "The session deadline is invalid.", "security", ); self.invalidate(s, error.clone()).await; return Err(error); } s.deadline = deadline; { let mut identity = self.inner.userData.lock().unwrap(); for key in ["features", "featureValues", "metadata"] { if let Some(value) = data.get(key) { identity[key] = value.clone(); } } } s.heartbeat_seconds = data["heartbeatSeconds"] .as_f64() .unwrap_or(600.0) .clamp(1.0, 3600.0); s.jitter_seconds = data["jitterSeconds"] .as_f64() .unwrap_or(15.0) .clamp(0.0, 15.0); Ok(()) } pub async fn checkSession(&self) -> Result { let mut s = self.inner.state.lock().await; let result = self .request(&mut s, "/v3/session/check", json!({}), true, true) .await?; self.lease(&mut s, &result.data).await?; Ok(result) } async fn protected(&self, path: &str, data: Value, retry: bool) -> Result { let mut s = self.inner.state.lock().await; if s.token.is_some() && s.now() >= s.deadline { let r = self .request(&mut s, "/v3/session/check", json!({}), true, true) .await?; self.lease(&mut s, &r.data).await? } self.request(&mut s, path, data, true, retry).await } pub fn initWith(&self, completed: F) -> tokio::task::JoinHandle<()> where F: FnOnce(Result) + Send + 'static, { let client = self.clone(); tokio::spawn(async move { completed(client.init().await); }) } pub fn licenseLoginWith(&self, key: String, completed: F) -> tokio::task::JoinHandle<()> where F: FnOnce(Result) + Send + 'static, { let client = self.clone(); tokio::spawn(async move { completed(client.licenseLogin(&key).await); }) } pub fn getVariableWith(&self, name: String, completed: F) -> tokio::task::JoinHandle<()> where F: FnOnce(Result) + Send + 'static, { let client = self.clone(); tokio::spawn(async move { completed(client.getVariable(&name).await); }) } pub fn getScriptWith( &self, name: String, revision: Option, completed: F, ) -> tokio::task::JoinHandle<()> where F: FnOnce(Result) + Send + 'static, { let client = self.clone(); tokio::spawn(async move { completed(client.getScript(&name, revision).await); }) } pub async fn getMetadata(&self) -> Result { self.protected("/v3/metadata/get", json!({}), true).await } pub async fn updateVariable(&self, name: &str, value: &str) -> Result { self.protected("/v3/data/set", json!({"name":name,"value":value}), false) .await } pub async fn getFeatures(&self) -> Result { self.protected("/v3/features/list", json!({}), true).await } pub async fn getFeature(&self, name: &str) -> Result { self.protected("/v3/features/get", json!({"name":name}), true) .await } pub async fn getAllMetadata(&self) -> Result { self.protected("/v3/metadata/list", json!({}), true).await } pub async fn getMetadataValue(&self, key: &str) -> Result { self.protected("/v3/metadata/get", json!({"key":key}), true) .await } pub async fn checkMetadata(&self, key: &str) -> Result { self.protected("/v3/metadata/check", json!({"key":key}), true) .await } pub async fn sendWebhook(&self, name: &str, data: Value) -> Result { self.protected( "/v3/webhooks/send", json!({"event":name,"data":data}), false, ) .await } pub async fn setMetadata(&self, key: &str, value: Value) -> Result { self.protected("/v3/metadata/set", json!({"key":key,"value":value}), false) .await } pub async fn checkFeature(&self, name: &str) -> Result { self.protected("/v3/features/check", json!({"name":name}), true) .await } pub async fn getVariable(&self, name: &str) -> Result { self.protected("/v3/data/get", json!({"name":name}), true) .await } pub async fn getScript(&self, name: &str, revision: Option) -> Result { let mut data = json!({"name":name}); if let Some(v) = revision { data["revision"] = v.into() } let result = self.protected("/v3/scripts/get", data, true).await?; let s = self.inner.state.lock().await; let payload = text(&result.data, "signedPayload"); let manifest: Value = serde_json::from_str(payload).map_err(|_| { err( "SCRIPT_INVALID", "The script could not be verified.", "security", ) })?; if manifest.get("issuedAt").is_some() || manifest.get("expiresAt").is_some() { let issued = manifest["issuedAt"].as_i64().unwrap_or(0); let expires = manifest["expiresAt"].as_i64().unwrap_or(0); if issued <= 0 || issued > s.now() + 30000 || expires <= s.now() || expires <= issued { return Err(err( "SCRIPT_INVALID", "The script could not be verified.", "security", )); } } if let Some(minimum) = manifest.get("minimumRevision") { if minimum.as_u64().unwrap_or(0) == 0 || manifest["revision"].as_u64().unwrap_or(0) < minimum.as_u64().unwrap_or(0) { return Err(err( "SCRIPT_INVALID", "The script could not be verified.", "security", )); } } let content = text(&result.data, "content"); let valid = self .inner .o .script_keys .get(text(&manifest, "keyId")) .map(|k| verify(k, payload, text(&result.data, "signature"))) .unwrap_or(false) && manifest == result.data["manifest"] && manifest["appId"] == s.app_id && manifest["name"] == name && revision.map(|v| manifest["revision"] == v).unwrap_or(true) && manifest["sha256"] == hash(content) && manifest["bytes"] == content.len(); if !valid { return Err(err( "SCRIPT_INVALID", "The script could not be verified.", "security", )); } Ok(result) } pub async fn saveOfflineAccess(&self) -> Result { let mut s = self.inner.state.lock().await; let challenge = self .request(&mut s, "/v3/offline/challenge", json!({}), true, false) .await? .data; let signature=self.sign(&json!({"challenge":challenge["payload"],"operation":{"action":"offlinePermit","sessionId":s.session_id}}).to_string()); let r = self .request( &mut s, "/v3/offline/permit", json!({"challengeId":challenge["challengeId"],"signature":signature}), true, false, ) .await?; s.offline = Some(Offline { app_id: s.app_id.clone(), identity_id: s.identity_id.clone(), permit: r.data.clone(), trusted_time: s.now(), local_time: wall(), }); if !self.valid_offline(&s) { self.clear_offline(&mut s).await?; return Err(err( "OFFLINE_INVALID", "The offline permit could not be verified.", "security", )); } self.persist(&mut s).await?; Ok(r) } fn valid_offline(&self, s: &State) -> bool { let Some(offline) = &s.offline else { return false; }; if s.logging_out || self.inner.life.is_cancelled() || wall() < s.anchor_wall { return false; } let payload = text(&offline.permit, "signedPayload"); if payload.len() > 4096 { return false; } let Ok(claims) = serde_json::from_str::(payload) else { return false; }; let id = text(&claims, "keyId"); let Some(key) = self.inner.o.offline_keys.get(id) else { return false; }; let issued = claims["issuedAt"].as_i64().unwrap_or(i64::MAX); let expires = claims["expiresAt"].as_i64().unwrap_or(i64::MIN); let now = s.now(); fingerprint(key).as_deref() == Some(id) && verify(key, payload, text(&offline.permit, "signature")) && claims["type"] == "authlyx.offline.v1" && claims["appId"] == s.app_id && claims["subjectId"] == s.identity_id && claims["installationKeyHash"] == self.inner.key_hash && issued <= now && now < expires && expires > issued && expires.saturating_sub(issued) <= 2592000000 && now >= offline.trusted_time } async fn persist(&self, s: &mut State) -> Result<(), Error> { let now = s.now(); if let Some(offline) = s.offline.as_mut() { offline.trusted_time = now; offline.local_time = wall(); self.inner .o .storage .save( &(self.inner.prefix.clone() + ".offline"), &serde_json::to_string(offline).unwrap(), ) .await? } Ok(()) } pub async fn hasOfflineAccess(&self) -> bool { let mut s = self.inner.state.lock().await; if !self.valid_offline(&s) { return false; } if self.persist(&mut s).await.is_err() { s.offline = None; return false; } true } pub async fn hasAccess(&self) -> bool { let mut s = self.inner.state.lock().await; if s.logging_out || self.inner.life.is_cancelled() { return false; } if s.token.is_some() && s.deadline > s.now() { return true; } if !self.valid_offline(&s) { return false; } if self.persist(&mut s).await.is_err() { s.offline = None; return false; } true } pub async fn logout(&self) -> Result<(), Error> { let client = self.clone(); tokio::spawn(async move { client.logout_inner().await }) .await .map_err(|_| { err( "LOGOUT_FAILED", "Logout cleanup could not finish.", "storage", ) })? } async fn logout_inner(&self) -> Result<(), Error> { let mut s = self.inner.state.lock().await; s.logging_out = true; self.stop_heartbeat(); let result = if s.token.is_some() { self.request(&mut s, "/v3/session/logout", json!({}), true, false) .await .map(|_| ()) } else { Ok(()) }; s.token = None; *self.inner.userData.lock().unwrap() = json!({}); s.deadline = 0; let clear = self.clear_offline(&mut s).await; result.and(clear) } fn start_heartbeat(&self) { self.stop_heartbeat(); if self.inner.o.manual_heartbeat { return; } let cancel = self.inner.life.child_token(); *self.inner.heartbeat.lock().unwrap() = Some(cancel.clone()); let weak = Arc::downgrade(&self.inner); tokio::spawn(async move { loop { let Some(inner) = weak.upgrade() else { return }; let client = AuthlyX { inner }; let duration = { let s = client.inner.state.lock().await; if s.token.is_none() || s.logging_out { return; } Duration::from_secs_f64( (s.heartbeat_seconds + (rand::random::() * 2.0 - 1.0) * s.jitter_seconds) .max(1.0), ) }; drop(client); tokio::select! {_ = cancel.cancelled()=>return,_ = tokio::time::sleep(duration)=>{}} let Some(inner) = weak.upgrade() else { return }; let client = AuthlyX { inner }; let _ = client.checkSession().await; drop(client); } }); } pub async fn onResume(&self) -> Result { self.checkSession().await } pub async fn close(&self) { self.inner.life.cancel(); self.stop_heartbeat(); let mut s = self.inner.state.lock().await; s.token = None; *self.inner.userData.lock().unwrap() = json!({}); s.deadline = 0; } } pub mod storage { use crate::{err, hash, Error}; use async_trait::async_trait; use std::{collections::HashMap, path::PathBuf}; use tokio::sync::Mutex; #[async_trait] pub trait ProtectedStore: Send + Sync { async fn load(&self, name: &str) -> Result, Error>; async fn save(&self, name: &str, value: &str) -> Result<(), Error>; async fn delete(&self, name: &str) -> Result<(), Error>; } #[derive(Default)] pub struct MemoryStore { values: Mutex>, } #[async_trait] impl ProtectedStore for MemoryStore { async fn load(&self, name: &str) -> Result, Error> { Ok(self.values.lock().await.get(name).cloned()) } async fn save(&self, name: &str, value: &str) -> Result<(), Error> { self.values.lock().await.insert(name.into(), value.into()); Ok(()) } async fn delete(&self, name: &str) -> Result<(), Error> { self.values.lock().await.remove(name); Ok(()) } } pub struct WindowsProtectedStore { directory: PathBuf, } impl WindowsProtectedStore { pub fn new(directory: PathBuf) -> Result { if !cfg!(windows) { return Err(err( "STORAGE_UNAVAILABLE", "Supply a platform-protected store.", "storage", )); } std::fs::create_dir_all(&directory).map_err(|_| { err( "STORAGE_INVALID", "Could not create protected storage.", "storage", ) })?; Ok(Self { directory }) } fn file(&self, name: &str) -> PathBuf { self.directory.join(hash(name) + ".dat") } } #[cfg(windows)] fn crypt(name: &str, value: &[u8], protect: bool) -> Result, Error> { use windows_sys::Win32::{ Foundation::LocalFree, Security::Cryptography::{CryptProtectData, CryptUnprotectData, CRYPT_INTEGER_BLOB}, }; let mut source = CRYPT_INTEGER_BLOB { cbData: value.len() as u32, pbData: value.as_ptr() as *mut u8, }; let mut entropy = CRYPT_INTEGER_BLOB { cbData: name.len() as u32, pbData: name.as_ptr() as *mut u8, }; let mut output = CRYPT_INTEGER_BLOB { cbData: 0, pbData: std::ptr::null_mut(), }; let result = unsafe { if protect { CryptProtectData( &mut source, std::ptr::null(), &mut entropy, std::ptr::null(), std::ptr::null_mut(), 1, &mut output, ) } else { CryptUnprotectData( &mut source, std::ptr::null_mut(), &mut entropy, std::ptr::null(), std::ptr::null_mut(), 1, &mut output, ) } }; if result == 0 { return Err(err( "STORAGE_INVALID", "Protected state could not be read or saved.", "storage", )); } let bytes = unsafe { let bytes = std::slice::from_raw_parts(output.pbData, output.cbData as usize).to_vec(); LocalFree(output.pbData as *mut _); bytes }; Ok(bytes) } #[cfg(not(windows))] fn crypt(_: &str, _: &[u8], _: bool) -> Result, Error> { Err(err( "STORAGE_UNAVAILABLE", "Supply a platform-protected store.", "storage", )) } #[async_trait] impl ProtectedStore for WindowsProtectedStore { async fn load(&self, name: &str) -> Result, Error> { let file = self.file(name); let bytes = match std::fs::read(file) { Ok(b) => b, Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None), Err(_) => { return Err(err( "STORAGE_INVALID", "Could not read protected state.", "storage", )) } }; if bytes.len() > 1048576 { return Err(err( "STORAGE_INVALID", "Protected state is too large.", "storage", )); } String::from_utf8(crypt(name, &bytes, false)?) .map(Some) .map_err(|_| err("STORAGE_INVALID", "Protected state is invalid.", "storage")) } async fn save(&self, name: &str, value: &str) -> Result<(), Error> { use std::io::Write; let file = self.file(name); let temp = file.with_extension(format!("{}.tmp", rand::random::())); let result = (|| { let mut stream = std::fs::OpenOptions::new() .create_new(true) .write(true) .open(&temp)?; stream.write_all( &crypt(name, value.as_bytes(), true).map_err(std::io::Error::other)?, )?; stream.sync_all()?; drop(stream); std::fs::rename(&temp, &file) })(); let _ = std::fs::remove_file(&temp); result.map_err(|_: std::io::Error| { err( "STORAGE_INVALID", "Could not save protected state.", "storage", ) }) } async fn delete(&self, name: &str) -> Result<(), Error> { match std::fs::remove_file(self.file(name)) { Ok(()) => Ok(()), Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()), Err(_) => Err(err( "STORAGE_INVALID", "Could not remove protected state.", "storage", )), } } } } ```