# 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.
ApplicationNorthstar EditorVersion2.4.0
Release channelStable
License detailsActive
8F2K-4N7P-9R3W-6Q5MPlanProfessional
Devices1 of 3
Expires30 Nov 2026
Session verified↗
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
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