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

# Enabling the Rasa REST API

> Read about Rasa's REST API that has endpoints for conversations, training models, and configuring your bot.

<Tip>
  **Looking for API endpoints?**

  Check out the [API Spec](/docs/reference/api/pro/http-api/server-information/health-endpoint-of-rasa-server) for all of the available endpoints as well as their request and response formats.
</Tip>

## Enabling the REST API

By default, running a Rasa server does not enable the API endpoints. Interactions
with the bot can happen over the exposed `webhooks/<channel>/webhook` endpoints.

To enable the API for direct interaction with conversation trackers and other
bot endpoints, add the `--enable-api` parameter to your run command:

```bash theme={null}
rasa run --enable-api
```

Note that you start the server with an NLU-only model, not all the available endpoints
can be called. Some endpoints will return a 409 status code, as a trained
dialogue model is needed to process the request.

<Warning>
  Make sure to secure your server, either by restricting access to the server (e.g. using firewalls), or
  by enabling an authentication method. See [Security Considerations](/docs/reference/api/pro/rasa-pro-rest-api#security-considerations).
</Warning>

By default, the HTTP server runs as a single process (`SANIC_WORKERS=1`). You can change the number
of worker processes using the `SANIC_WORKERS` environment variable. It is
recommended that you set the number of workers to the number of available CPU cores
(check out the
[Sanic docs](https://sanicframework.org/en/guide/deployment/running.html#workers)
for more details). This will only work in combination with the
`RedisLockStore` (see [Lock Stores](/docs/reference/integrations/lock-stores)).

As of Rasa Pro 3.19, the server runs on Sanic 25, which spawns each worker as a
separate process and rebuilds the application within it. This has two
user-visible effects when `SANIC_WORKERS` is greater than `1`:

* `GET /status` includes a `worker_pid` field that reports the process ID of the
  worker that handled the request.
* `PUT /model` and `DELETE /model` only affect the worker that handles the
  request. Set `SANIC_WORKERS=1` when loading or unloading models at runtime.

<Warning>
  The [SocketIO channel](/docs/reference/channels/your-own-website#socketio-channel) does not support multiple worker processes.
</Warning>

## Security Considerations

We recommend that you don't expose the Rasa Server to the outside world directly, but
rather connect to it via e.g. Nginx.

Nevertheless, there are two authentication methods built in:

### Token Based Auth

To use a plaintext token to secure your server, specify the token in the argument `--auth-token thisismysecret` when starting
the server:

```bash theme={null}
rasa run \
    --enable-api \
    --auth-token thisismysecret
```

You can also use environment variable `AUTH_TOKEN` to set the auth token:

```
AUTH_TOKEN=thisismysecret
```

<Tip>
  **Security best practice**

  We recommend that you use environment variables to store
  and share sensitive information such as tokens and secrets
  when deploying Rasa as Docker container as they will not be stored in your shell history.
</Tip>

Any clients sending requests to the server must pass the token
as a query parameter, or the request will be rejected. For example, to fetch a tracker from the server:

```bash theme={null}
curl -XGET localhost:5005/conversations/default/tracker?token=thisismysecret
```

### JWT Based Auth

To use JWT based authentication, specify the JWT secret in the argument `--jwt-secret thisismysecret`
on startup of the server:

```bash theme={null}
rasa run \
    --enable-api \
    --jwt-secret thisismysecret
```

You can also use environment variable `JWT_SECRET` to set the JWT secret:

```
JWT_SECRET=thisismysecret
```

<Tip>
  **Security best practice**

  We recommend that you use environment variables to store
  and share sensitive information such as tokens and secrets
  when deploying Rasa as Docker container as they will not be stored in your shell history.
</Tip>

If you want to sign a JWT token with asymmetric algorithms, you can specify the JWT private key to the `--jwt-private-key`
CLI argument. You must pass the public key to the `--jwt-secret` argument, and also specify the algorithm to the
`--jwt-method` argument:

```bash theme={null}
rasa run \
    --enable-api \
    --jwt-secret <public_key> \
    --jwt-private-key <private_key> \
    --jwt-method RS512
```

You can also use environment variables to configure JWT:

```
JWT_SECRET=<public_key>
JWT_PRIVATE_KEY=<private_key>
JWT_METHOD=RS512
```

<Tip>
  **Security best practice**

  We recommend that you use environment variables to store
  and share sensitive information such as tokens and secrets
  when deploying Rasa as Docker container as they will not be stored in your shell history.
</Tip>

Client requests to the server will need to contain a valid JWT token in
the `Authorization` header that is signed using this secret
and the `HS256` algorithm e.g.

```text theme={null}
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ"
                 "zdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIi"
                 "wiaWF0IjoxNTE2MjM5MDIyfQ.qdrr2_a7Sd80gmCWjnDomO"
                 "Gl8eZFVfKXA6jhncgRn-I"
```

The token's payload must contain an object under the `user` key,
which in turn must contain the `username` and `role` attributes.
The following is an example payload for a JWT token:

```json theme={null}
{
  "user": {
    "username": "<sender_id>",
    "role": "user"
  }
}
```

If the `role` is `admin`, all endpoints are accessible.
If the `role` is `user`, endpoints with a `sender_id` parameter are only accessible
if the `sender_id` matches the payload's `username` property.

For the [user trackers endpoint](/docs/reference/api/pro/http-api/tracker/retrieve-all-conversations-for-a-user) (`GET /users/{user_id}/trackers`), you should use `user_id` instead of `username` in the payload.
In this case, the path `user_id` parameter is matched against the payload's `username` property. For example:

```json theme={null}
{
  "user": {
    "username": "<user_id>",
    "role": "user"
    }
}
```

To create and encode the token, you can use tools such as the [JWT Debugger](https://jwt.io/), or a Python module such as [PyJWT](https://pyjwt.readthedocs.io/en/latest/).