Enabling the Rasa REST API - Rasa Documentation

Looking for API endpoints?Check out the API Spec for all of the available endpoints as well as their request and response formats.

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:

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.

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.

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 for more details). This will only work in combination with the RedisLockStore (see 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.

The SocketIO channel does not support multiple worker processes.

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:

rasa run \
    --enable-api \
    --auth-token thisismysecret

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

AUTH_TOKEN=thisismysecret

Security best practiceWe 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.

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:

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:

rasa run \
    --enable-api \
    --jwt-secret thisismysecret

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

JWT_SECRET=thisismysecret

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:

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

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.

"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:

{
  "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 (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:

{
  "user": {
    "username": "<user_id>",
    "role": "user"
    }
}

To create and encode the token, you can use tools such as the JWT Debugger, or a Python module such as PyJWT.

​Enabling the REST API

​Security Considerations

​Token Based Auth

​JWT Based Auth

Enabling the REST API

Security Considerations

Token Based Auth

JWT Based Auth