auth
Published: March 2025 | Last updated: May 2025
Overview
The auth RPC method authenticates a Tenant for a time-limited session on the Lynx blockchain. This authentication process establishes the user's identity and permissions, enabling them to perform storage operations appropriate to their role. Authentication sessions have a fixed duration of approximately 6 hours (72 blocks), after which re-authentication is required.
Syntax
Description
When you invoke the auth method with a valid private key, the Lynx daemon verifies your identity against its list of authorized users and establishes a session that grants you access to role-appropriate commands. For security purposes, the command automatically disables staking for authenticated tenants. The private key used by the auth method is stored in the lynx.conf file. Since the private key is respective to the mainnet or testnet environments, the 'rpctenent' key is prefixed with the environment name. Examples of both are below.
During authentication, the system evaluates your wallet's capacity to support storage operations, which directly determines the maximum storage capacity by the local daemon. This helps ensure that users have sufficient resources to complete their intended storage operations.
Parameters
[environment].rpctenant referenced from ~/.lynx/lynx.conf file
string
Yes
A valid WIF-format private key associated with an authorized tenant. This key proves your identity to the system.
Returns
The method returns an array containing a single object with the following fields:
result
string
Indicates whether authentication succeeded (success) or failed (failure).
message
string
Provides additional information about the result: You are authenticated as a tenant, Invalid key, Unauthorized tenant, or No wallet.
capacity
number
The maximum storage capacity available to the Tenant in kilobytes (KB).
sessionstart
string
The timestamp when the authentication session began in YYYY-MM-DD HH:MM:SS format.
sessionend
string
The timestamp when the authentication session will expire in YYYY-MM-DD HH:MM:SS format.
sessionstartblock
string/number
The blockchain height when the authentication session began.
sessionendblock
string/number
The blockchain height when the authentication session will expire (start block + 72).
stakingstatus
string
Indicates whether staking is currently enabled or disabled on the node. Always set to disabled for regular tenants during their session.
Authentication Security
The authentication system implements several security measures:
Progressive Delay: Failed authentication attempts introduce an exponentially increasing delay (doubling with each failure) to suppress brute force attacks.
Session Expiration: Authentication sessions for regular tenants expire after approximately 6 hours (72 blocks).
Staking Management: Staking is automatically disabled for regular tenants during their session to prevent resource conflicts. If staking is enabled in the lynx.conf file, staking will be enabled after the authorized tenant session expires.
Tenant Capacity Calculation
The system calculates a tenant's storage capacity based on the number of UTXO in their wallet:
This calculation helps tenants understand their maximum storage allocation
Examples
Authenticate as a tenant
Output for a successful tenant authentication:
Using JSON-RPC:
Error Handling
The method will return a failure result in the following scenarios:
Invalid Key: The provided private key is empty or invalid (cannot be used to derive a valid user)
Unauthorized Tenant: The key is valid but not registered as an authorized tenant in the system
No Wallet: The system doesn't have a wallet available for the authentication process
Each of these errors will trigger the progressive delay mechanism to suppress brute force attacks.
Last updated
