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.

Access Token

Static token to be used as a bearer token. Only the latest token is valid at any time.

App User Credentials with Basic Auth

Use the same credentials as the Flow Director app login. Authenticated via HTTP Basic Auth. 

App User Credentials with JSON Web Token

Use the same credentials as the Flow Director app login. Authenticated via JWT (bearer token).

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" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NzEzMDIxMzIsInVzZXJuYW1lIjoiYWRtaW4ifQ.GmX7cJZk8A3KWybyKwajtURRRVlm5BkgbAg009-1Znc"
}

Include the token in your request to an authenticated route.

Within the request handler flow, you can access the token information under _token. Every token includes a username and an iat value for the issued at UNIX timestamp you may use to expire old tokens.

{
  "_token": {
    "iat": 1571302417,
    "username":"admin"
  }
}

Custom Flow with Basic Auth

Validate the username and password using your own custom logic.

Listen for the request at <app>.auth.custom, and send any valid JSON for successful response. To send an invalid credentials response, set the status code to any 4XX error code.

Like validation via app credentials, you can access the credentials used under _token in the request body.

Custom Flow with JSON Web Token

This allows you to validate your own custom payload instead of a username & password credential.

First create your auth validation flow that will listen at <app>.auth.custom.

On a successful response, you can specify your custom token payload.

To get a token, make a POST request to /api/<app>/auth/token with your custom JSON body.

For the above example:

{
  "fruit": "cantaloupe"
}

Will return a token you may use to authenticate protected routes.

{
  "token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJtZXNzYWdlIjoiT0siLCJpYXQiOjE1NzEzMDM5NTZ9.Zxu2g7Opm7woVTOZgjmhAZiIM00FblRNpnGNzT0htT4"
}

The original payload is included within the request handler flow and the iat value for token issued at the timestamp.

The above token would contain the following under _token in the request body.

{
  "is_awesome" : true,
  "iat" : 1571304269,
  "fruit" : "cantaloupe"
}