> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperbeam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticating Participants

> Granting access to cloud computers

When a user attempts to connect to a cloud computer, we need to identify the user and determine whether they should be granted access.

## Authentication Strategies

### Token Authentication

* This is the default authentication strategy
* No additional code is needed

### Webhook Authentication

* You need to create an endpoint on your backend (i.e. a webhook)
* The virtual computer will hit your endpoint when a new user tries to connect
* Your backend's webhook response controls whether the user is granted access
* To set the authentication strategy, you provide an authentication object when starting a cloud computer session:

### Setting the Authentication Strategy

To set the authentication strategy, you provide an authentication object when starting a cloud computer session:

**Token Authentication (Default)**

```json theme={null}
{
  "auth": {
    "type": "token"
  }
}
```

**Webhook Authentication**

```json theme={null}
{
    "auth": {
    "type": "webhook",
    "value": {
      "url": "https://yourwebsite.com/webhook/hyperbeam/auth"
      "bearer": "<cryptographic-key>"
    }
  }
}
```

#### Request Body

| Property            | Type   | Description                                                                                    |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `auth.type`         | string | The authentication strategy type. Valid values are `webhook` and `token`.                      |
| `auth.value.url`    | string | The endpoint of your webhook for webhook-based authentication.                                 |
| `auth.value.bearer` | string | A secret cryptographic key you provide to verify the webhook request is coming from Hyperbeam. |

## In-Depth

### Token Authentication

When using token authentication, a token is added as a query parameter to the cloud computer’s embed URL. This ensures only users that were provided the embed URL have access to the cloud computer—malicious actors cannot gain access via the session ID or brute force.

### Webhook Authentication

Start a cloud computer session with webhook authentication

```bash theme={null}
curl -X POST -H 'Authorization: Bearer <your-api-key>' \
    https://engine.hyperbeam.com/v0/vm \
    -d '{
      "auth": {
        "type": "webhook",
        "value": {
          "url": "https://yourwebsite.com/webhook/hyperbeam/auth",
          "bearer": "<secret-key>"
        }
      }
    }'
```

You will need to create an endpoint on your backend. The cloud computer will send a request to the endpoint you provided to determine if a user is allowed to connect.

Our request will:

* Set the `Authorization` header to `Authorization: Bearer <bearer-token>`
  * `<bearer-token>` is the token you provided in the authentication object
* Set the `HB-User-Agent` header to the client's user agent
* Set the `HB-Connection-IP` header to the client's IP address
* Send a `POST` request with a JSON request body
  * `user_id` is the user's [Hyperbeam identifier](/client-sdk/javascript/examples#getting-user-id)
  * `userdata` is the `webhookUserdata` object passed into the Hyperbeam [JavaScript SDK](/client-sdk/javascript/overview)

```json theme={null}
{
  "user_id": "7411d16b-9451-415e-bb65-7d5ff3202249",
  "userdata": {}
}
```

TL;DR: our request will look like this:

```bash theme={null}
curl -X POST -H 'Authorization: Bearer <bearer-token>' \
    -H 'Content-Type: application/json' \
    -H 'HB-User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36' \
    -H 'HB-Connection-IP: 203.0.113.195' \
    https://yourwebsite.com/webhook/hyperbeam/auth \
    -d '{"user_id": "7411d16b-9451-415e-bb65-7d5ff3202249", "userdata": {"my_data": "foo"}}'
```

Testing webhooks is difficult when running your backend locally (e.g. our cloud computers cannot reach `localhost:8080`). We recommend using [ngrok](https://ngrok.com/) to expose your endpoint for testing.

Your webhook must:

* Check that the bearer token in the Authorization header matches the token you provided

* Parse the request body and determine if the user should be granted access

  * You can use the `user_id` and userdata fields to identify the user

* Send back a `200` status with a JSON response body
  * To grant user access, send back `{"authorized": true}`
  * To deny user access, send back `{"authorized": false}`
  * Any response that doesn't have a 200 status code will deny user access
  * If the "authorized" key is not set, the user will be denied
  * You can provide a permissions object in the response to atomically set the [permission values](/client-sdk/javascript/examples#setting-permissions) of the user