# Connect with a bot user

With **Bot user**, the gateway signs in at your API's own login route with a dedicated user, keeps the token and sends it on every call. Use it when your API authenticates with a username and password and returns a token or a session cookie.

## Before you begin

- Create a dedicated user for Faustine in each deployment, such as `faustine-bot`. Do not use a person's account.
- The login must not require multi-factor authentication. MFA-protected logins are not supported.

## How the gateway signs in

On the first call through a connection, the gateway sends the connection's username and password as JSON to the login route. It reads the token from the response body or from a cookie and adds it to the call.

The gateway keeps the token until it expires and signs in again when it does. It also signs in again when a call answers `401`. If the API has a **Refresh route**, the gateway calls it first and falls back to a full login when the refresh is refused.

Your API sees one user for all agent traffic through that connection.

## Set the strategy on the API

The analysis fills in these fields when it finds the login route in the code. Check them, or enter them by hand.

1. In the portal, go to [**APIs**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) and select your API.
2. Select the **Authentication** tab, then **Edit**.
3. In **Sign-in method**, select **Bot user**.
4. Fill in the fields in **Login request**, **Token** and **Sending it**.
5. Select **Save changes**.

| Field | Description | Default |
| --- | --- | --- |
| **Login route** | A path on the connection's host, such as `/auth/login`, or a full URL when the login lives on another host. | |
| **Method** | **POST** or **PUT**. | **POST** |
| **Username field** | The name of the username field in the request body. | `email` |
| **Password field** | The name of the password field in the request body. | `password` |
| **Other body fields** | JSON sent with every login. | |
| **Refresh route** | Optional. Called before signing in again. | |
| **The token comes back in** | **The JSON body** or **A cookie**. | **The JSON body** |
| **Path in the body** | Where the token is in the response, such as `token` or `data.accessToken`. | `token` |
| **Cookie name** | The cookie whose value is the token, when the token comes back in a cookie. | |
| **Expiry** | **From the token itself (JWT exp)**, **After a fixed time** with a number of **Seconds**, or **When a call answers 401**. | **From the token itself (JWT exp)** |
| **Sent on every call as** | **Header**, **Cookie** or **Query**, with the **Header name**, **Cookie name** or **Parameter name**. | **Header**, `Authorization` |
| **Prefix** | Put before the token in a header. | `Bearer ` |

## Add the user to a connection

To store the bot user's credentials for one deployment, [add a connection](https://docs.faustine.ai/apis/add-a-connection/) and enter the **Username** and **Password** of the bot user in the **Credentials** step.

The test signs in and then calls the operation, so **Reached the endpoint** with a `2xx` status confirms both the login and the token.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `Upstream login failed (401)` | Your API refused the username or password. | Correct the values in the connection. Check that **Username field** matches the field the login reads. |
| `Upstream login response has no token at "token"` | The token is somewhere else in the response. | Set **Path in the body**, or select **A cookie** and enter the **Cookie name**. |
| `Bot user needs the login route` | **Login route** is empty. | Enter it in the **Authentication** tab. |
| Calls answer `401` right after a successful login | Your API reads the token from a different header or cookie. | Change **Sent on every call as**, the name and the **Prefix**. |

## Next steps

- [Authentication](https://docs.faustine.ai/apis/authentication/): token exchange, for an API that swaps the login token for another one.
- [Write a custom sign-in script](https://docs.faustine.ai/apis/custom-sign-in-script/): for a login that takes more than one request.
- [Add an API to a gateway](https://docs.faustine.ai/agent-gateway/add-an-api/): serve the API through the connection.