# allow (restricted)

### Overview

The `allow` RPC method adds a new authorized tenant to the Lynx blockchain storage system. This command enables the blockchain administrator to grant storage privileges to new tenants by registering their public key hash in the authentication system. Once added, the new tenant can authenticate and begin storing data on the blockchain.

### Syntax

```
allow <hash160>
```

### Description

When you invoke the `allow` method as the blockchain manager, the Lynx daemon creates and broadcasts a special transaction containing authentication data that registers a new tenant in the system. This transaction includes a timestamped payload with the tenant's identifier, which is permanently recorded on the blockchain. This process establishes an immutable record of tenant authorization that can be verified by all nodes in the network.

The authorization process is designed with strong access controls to ensure that only the designated blockchain manager can add new tenants, protecting the integrity of the storage system's authentication mechanism.

### Parameters

| Parameter | Type   | Required | Description                                                                                                                                                                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hash160` | string | Yes      | The RIPEMD-160 hash of the new tenant's public key in hexadecimal format. This is a 40-character hexadecimal string (e.g., `00112233445566778899aabbccddeeff00112233`) that uniquely identifies the tenant. |

### Returns

The method returns an array containing one or more status messages:

For successful operations:

```
[
  "success",
  "00112233445566778899aabbccddeeff00112233"
]
```

For failed operations, the array will contain a descriptive error message indicating the reason for failure:

```
[
  "hash160-wrong-size"
]
```

Possible status messages include:

* `success` - The tenant has been successfully added to the system
* `hash160-wrong-size` - The provided hash is not the correct length (must be 40 hexadecimal characters)
* `Role-based restriction: Current role cannot perform this action` - The authenticated user is not the blockchain manager
* `error-generating-authpayload` - An error occurred while generating the authentication payload
* `error-generating-authtransaction` - An error occurred while creating the authentication transaction
* `authentication failure` - The user is not authenticated or the authentication has expired
* `failure` - A general failure occurred (rarely seen, as more specific errors are usually provided)

### Access Control

The `allow` command has strict access control requirements:

* Only the blockchain manager (initial authentication user defined in consensus parameters) can execute this command
* The manager must be authenticated via the `auth` command before using `allow`
* Regular tenants cannot add other tenants, even if they are authenticated
* This role-based restriction ensures centralized control over tenant authorization

### Authentication Transaction

When a new tenant is added, the system:

1. Generates a special authentication payload containing:
   * Operation type (0 for adding a tenant)
   * Current timestamp
   * The tenant's hash160 identifier
2. Creates a blockchain transaction with this payload embedded as an OP\_RETURN output
3. Broadcasts this transaction to the network, where it will be mined into a block

This transaction serves as a permanent, immutable record of tenant authorization that all nodes can verify.

### Examples

#### Add a new tenant

As the blockchain manager:

```
lynx-cli allow 00112233445566778899aabbccddeeff00112233
```

Output:

```
[
  "success",
  "00112233445566778899aabbccddeeff00112233"
]
```

Using JSON-RPC:

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

### Error Handling

The method will return a failure message in the following scenarios:

* The provided hash160 is not exactly 40 characters long (20 bytes in hexadecimal)
* The user is not authenticated or is not authenticated as the blockchain manager
* There is an error in generating the authentication payload or transaction
* The authentication system cannot validate the current user's credentials

### Implementation Notes

* The command verifies the user's authentication status using the `is_auth_member` function
* It validates that the authenticated user is the blockchain manager using consensus parameters
* The current timestamp is obtained using `TicksSinceEpoch<std::chrono::seconds>(GetAdjustedTime())`
* The authentication payload is generated with the `generate_auth_payload` function
* The authentication transaction is created and broadcast with the `generate_auth_transaction` function
* The system performs validation checks on both the tenant identifier and the transaction creation process


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.getlynx.io/lynx-core/data-storage/allow-restricted.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.