# auth

### 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

```
lynx-cli auth
```

### 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.

{% code title="\~/.lynx/lynx.conf" %}

```
# mainnet tenant key
main.rpctenant=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

# Commented testnet tenant key
# test.rpctenant=d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
```

{% endcode %}

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

<table><thead><tr><th width="289.43121337890625">Parameter</th><th width="92.96246337890625">Type</th><th width="101.0843505859375">Required</th><th>Description</th></tr></thead><tbody><tr><td>[environment].rpctenant referenced from ~/.lynx/lynx.conf file </td><td>string</td><td>Yes</td><td>A valid WIF-format private key associated with an authorized tenant. This key proves your identity to the system.</td></tr></tbody></table>

### Returns

The method returns an array containing a single object with the following fields:

<table><thead><tr><th width="237">Field</th><th width="168">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>result</code></td><td>string</td><td>Indicates whether authentication succeeded (<code>success</code>) or failed (<code>failure</code>).</td></tr><tr><td><code>message</code></td><td>string</td><td>Provides additional information about the result: <code>You are authenticated as a tenant</code>, <code>Invalid key</code>, <code>Unauthorized tenant</code>, or <code>No wallet</code>.</td></tr><tr><td><code>capacity</code></td><td>number</td><td>The maximum storage capacity available to the Tenant in kilobytes (KB). </td></tr><tr><td><code>sessionstart</code></td><td>string</td><td>The timestamp when the authentication session began in <code>YYYY-MM-DD HH:MM:SS</code> format.</td></tr><tr><td><code>sessionend</code></td><td>string</td><td>The timestamp when the authentication session will expire in <code>YYYY-MM-DD HH:MM:SS</code> format.</td></tr><tr><td><code>sessionstartblock</code></td><td>string/number</td><td>The blockchain height when the authentication session began.</td></tr><tr><td><code>sessionendblock</code></td><td>string/number</td><td>The blockchain height when the authentication session will expire (start block + 72). </td></tr><tr><td><code>stakingstatus</code></td><td>string</td><td>Indicates whether staking is currently <code>enabled</code> or <code>disabled</code> on the node. Always set to <code>disabled</code> for regular tenants during their session.</td></tr></tbody></table>

### 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

```
lynx-cli auth
```

Output for a successful tenant authentication:

```
[
  {
    "result": "success",
    "message": "You are authenticated as a tenant.",
    "capacity": 63569,
    "sessionstart": "2025-03-24 21:34:40",
    "sessionend": "2025-03-25 03:34:40",
    "sessionstartblock": 3108065,
    "sessionendblock": 3108137,
    "stakingstatus": "disabled"
  }
]
```

Using JSON-RPC:

```
curl --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "auth", "params": []}' -H 'content-type: text/plain;' http://127.0.0.1:9332/
```

### 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.