# Authentication and Authorization for JSON-RPC

Authentication identifies a user based on a username and password. Authorization verifies whether the user has
access to the JSON-RPC method they are requesting.  

Pantheon uses the username and password to authenticate users and [JWT tokens](https://jwt.io/introduction/) to authorize JSON-RPC requests. 

!!! important 
    Authenticated requests must be made over HTTPS. HTTPS is encrypted which prevents eavesdropping on the connection
    to obtain the JWT token from the requests.

## Credentials File 

The credentials file is a `toml` file defining user details and the JSON-RPC methods to which they have access. 

!!! example "Example Credentials File"
    ```toml
    [Users.username1]
    password = "$2a$10$l3GA7K8g6rJ/Yv.YFSygCuI9byngpEzxgWS9qEg5emYDZomQW7fGC"
    permissions=["net:*","eth:blockNumber"]
    
    [Users.username2]
    password = "$2b$10$6sHt1J0MVUGIoNKvJiK33uaZzUwNmMmJlaVLkIwinkPiS1UBnAnF2"
    permissions=["net:version","admin:*"]
    ```

Each user requiring JSON-RPC access is listed with: 

* Username. `Users.` is mandatory and followed by the username. That is, replace `<username>` in `[Users.<username>]` with the username being defined. 
* Hash of the user password. Use the [`password hash`](../Reference/Pantheon-CLI-Syntax.md#password) subcommand to generate the hash. 
* JSON-RPC permissions. 

!!! example "password hash Subcommand"
    ```bash
    pantheon password hash --password=pegasys
    ```
    
## JSON-RPC Permissions 

Each user has a list of permissions strings defining the methods they can access. To give access to: 

* All API methods, specify `["*:*"]`.
* All API methods in an API group, specify `["<api_group>:*"]`. For example, `["eth:*"]`. 
* Specific API methods, specify `["<api_group>:<method_name>"]`. For example, `["admin:peers"]`.

If authentication is enabled, to explicitly specify a user cannot access any methods, include the user with an empty permissions list (`[]`). 
Users with an empty permissions list and users not included in the credentials file cannot access any JSON-RPC
methods. 
    
## Enabling Authentication 
 
Use the [` --rpc-http-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-enabled) or 
 [`--rpc-ws-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-enabled)
 options to require authentication for the JSON-RPC API.
  
Use the [`--rpc-http-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-credentials-file)
and [`--rpc-ws-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-credentials-file) 
options to specify the [credentials file](#credentials-file).  

!!!note
    The [`--rpc-http-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-credentials-file) 
    and [`--rpc-ws-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-credentials-file) 
    options are not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md). 
    Use a bind mount to [specify a credentials file with Docker](../Getting-Started/Run-Docker-Image.md#credentials-files).

## Obtaining an Authentication Token 

To obtain an authentication token, make a request to the `/login` endpoint with your username and password. 

!!! example
    ```bash tab="curl HTTPS request"
    $ curl -X POST --data '{"username":"username1","password":"pegasys"}' <JSON-RPC-https-endpoint:port>/login
    ```
    
    ```json tab="JSON result"
    {"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MDYwNCwiZXhwIjoxNTUwNDYwOTA0fQ.l2Ycqzl_AyvReXBeUSayOlOMS_E8-DCuz3q0Db0DKD7mqyl6q-giWoEtfdWzUEvZbRRi2_ecKO3N6JkXq7zMKQAJbVAEzobfbaaXWcQEpHOjtnK4_Yz-UPyKiXtu7HGdcdl5Tfx3dKoksbqkBl3U3vFWxzmFnuu3dAISfVJYUNA"}
    ``` 

Authentication tokens expire 5 minutes after being generated. It is necessary to generate a new authentication 
token if access is required after token expiration.     
    
## Using an Authentication Token to Make Requests 

Specify the authentication token as a `Bearer` token in the JSON-RPC request header. 

### Postman

In the _Authorization_ tab in the _TYPE_ drop-down list, select *Bearer Token* and specify the token 
generated by the [`login` request](#obtaining-an-authentication-token). 

### Curl

Specify the `Bearer` in the header. 

!!! example
    ```bash tab="curl Request with Authentication Placeholders"
    curl -X POST -H 'Authorization: Bearer <JWT_TOKEN>' -d '{"jsonrpc":"2.0","method":"<API_METHOD>","params":[],"id":1}' <JSON-RPC-https-endpoint:port>
    ```
    
    ```bash tab="curl Request with Authentication"
    curl -X POST -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MTQxNiwiZXhwIjoxNTUwNDYxNzE2fQ.WQ1mqpqzRLHaoL8gOSEZPvnRs_qf6j__7A3Sg8vf9RKvWdNTww_vRJF1gjcVy-FFh96AchVnQyXVx0aNUz9O0txt8VN3jqABVWbGMfSk2T_CFdSw5aDjuriCsves9BQpP70Vhj-tseaudg-XU5hCokX0tChbAqd9fB2138zYm5M' -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' https://localhost:8545
    ```