Connect with a bot user | Faustine Docs

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.

In the portal, go to APIs and select your API.
Select the Authentication tab, then Edit.
In Sign-in method, select Bot user.
Fill in the fields in Login request, Token and Sending it.
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 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: token exchange, for an API that swaps the login token for another one.
Write a custom sign-in script: for a login that takes more than one request.
Add an API to a gateway: serve the API through the connection.