Authenticate Routes
There are 5 different ways to authenticate your REST routes. Each is different in terms of complexity and flexibility; you should choose the simplest method for your use-case.
API Key
Static token to be used as a bearer token. Only the latest token is valid at any time.
![](../__attachments/1241809621/image-20230708-114427.png?inst-v=57e5ca98-7f43-4ba8-b604-92fea0b0cd31)
App User Credentials with Basic Auth
Use the same credentials as the Flow Director app login. Authenticated via HTTP Basic Auth.
![](../__attachments/1241809621/image-20230708-114459.png?inst-v=57e5ca98-7f43-4ba8-b604-92fea0b0cd31)
App User Credentials with JSON Web Token
Use the same credentials as the Flow Director app login. Authenticated via JWT (bearer token).
![](../__attachments/1241809621/image-20230708-114528.png?inst-v=57e5ca98-7f43-4ba8-b604-92fea0b0cd31)
To retrieve a token, make a POST request to /api/<app>/auth/token
with the body's username
and password
.
{
"username": "admin",
"password": "changeme"
}
If the credentials were correct, you would receive a token in the response.
{
"token_type": "bearer",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwiaWF0IjoxNjg4ODE2NzQ0LCJleHAiOjE2ODg4MzQ3NDR9.1jMGsDILVAik6KIM2z1xqalITxiCEDYNeViSlmYvQ_M",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwidHlwZSI6InJlZnJlc2giLCJpYXQiOjE2ODg4MTY3NDQsImV4cCI6MTY5MDAyNjM0NCwic3ViIjoicmVmcmVzaCJ9.qE7LbudFYXjwb-LKWNbX3C3bAUT9iVDrfSLBmxzWCL4"
}
Include the access_token
in your request to an authenticated route.
Within the request handler flow, you can access the token information under _token
. Every token includes the username
.
{
"_token": {
"username":"admin"
}
}
Custom Flow with Basic Auth
Validate the username
and password
using your own custom logic, for example, against a user database.
![](../__attachments/1241809621/image-20230708-114745.png?inst-v=57e5ca98-7f43-4ba8-b604-92fea0b0cd31)
You need to validate each request. The credentials are included in the request body under _token
:
{
"_token": {
"username":"admin",
"password":"changeme"
}
}
Custom Flow with JSON Web Token
This allows you to validate your own custom payload.
![](../__attachments/1241809621/image-20230708-123819.png?inst-v=57e5ca98-7f43-4ba8-b604-92fea0b0cd31)
First create your auth validation flow that will listen at <app>.auth.custom
.
![](../__attachments/1241809621/image-20210322-111036.png?inst-v=57e5ca98-7f43-4ba8-b604-92fea0b0cd31)
On a successful response, you can specify your custom token payload.
![](../__attachments/1241809621/image-20210322-111108.png?inst-v=57e5ca98-7f43-4ba8-b604-92fea0b0cd31)
To get a token, make a POST request to /api/<app>/auth/token
with your custom JSON body.
For the above example:
{
"fruit": "cantaloupe"
}
This will return an access_token
you can use to authenticate protected routes (bearer token).
{
"token_type": "bearer",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6Im11ZWxsaSIsImlhdCI6MTY4ODgxOTgwOCwiZXhwIjoxNjg4ODM3ODA4fQ.MXFj36hLULmUFVlLNtD4PVuqoKzvufwS82Qm8DLsvbI",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6Im11ZWxsaSIsInR5cGUiOiJyZWZyZXNoIiwiaWF0IjoxNjg4ODE5ODA4LCJleHAiOjE2OTAwMjk0MDgsInN1YiI6InJlZnJlc2gifQ.EfbAkdZjVOnZKPkz8Hl577GyZ0svUqgkm6Pa099GVBI"
}
The original payload returned from the authentication flow is included within the request handler flow of the protected route.
The above token would contain the following under _token
in the request body.
{
"is_awesome" : true,
"fruit" : "cantaloupe"
}
If a http status of 4XX
is returned from the authentication flow or the protected route, the body will contain a message why the authentication failed.
An access_token can be refreshed any time before expiration (5 hours). Do do that, send a request to route api/<app/refresh_token
which will return a new access_token
and refresh_token
.