Skip to main content
Version: v0.14

Local Authentication

The Authentication module offers a local email address based authentication strategy available for users to register with right out of the box.
Making use of it does not require any administrative intervention other than simply bringing up the Authentication module.

In this tutorial, we'll be utilizing Conduit's REST API to create and authenticate our users.<br

User Creation​

Request
curl --location --request POST 'http://localhost:3000/authentication/local' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "email": "example@mail.com",
        "password": "I_h4t3_p4ss_r3qu1r3m3nts"
      } '
Response
{
  "userId": "6242f1bb10a09901827738fe",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyNDJmMWJiMTBhMDk5MDE4Mjc3MzhmZSIsImlhdCI6MTY0ODU1NDUyNywiZXhwIjoxNzM0OTU0NTI3fQ.Fjqa7ORBBF2giwG7OgiWr2HMgHDL7R6ddFq2E730Djc",
  "refreshToken": "BsKhe3ARhL/FfDfK1REphKkkqQaxRCj/LvvRHOg5wCXCBaUSOwafRHyFYIttaORY/NmHS7NAuT6+knBQegVOwQ=="
}

User Authentication​

Having created our first user, it's time to d-d-d-d d-d-d-d-d-d-duel generate an authentication token.
Send a POST request to /authentication/local, passing in your user credentials.

Request
curl --location --request POST 'http://localhost:3000/authentication/local' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "email": "example@mail.com",
        "password": "I_h4t3_p4ss_r3qu1r3m3nts"
      }'
Response
{
  "userId": "6242f1bb10a09901827738fe",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyNDJmMWJiMTBhMDk5MDE4Mjc3MzhmZSIsImlhdCI6MTY0ODU1NDUyNywiZXhwIjoxNzM0OTU0NTI3fQ.Fjqa7ORBBF2giwG7OgiWr2HMgHDL7R6ddFq2E730Djc",
  "refreshToken": "BsKhe3ARhL/FfDfK1REphKkkqQaxRCj/LvvRHOg5wCXCBaUSOwafRHyFYIttaORY/NmHS7NAuT6+knBQegVOwQ=="
}

Nice, we got more of these weird sequences of seemingly random characters.

In order for your users to perform user authenticated application requests you'll need to pass their accessToken as an authorization header.

Now, what about that refreshToken then? User access tokens are only valid for a fairly short amount of time. Refresh tokens take longer to expire, therefore you may conveniently generate new authentication tokens without storing sensitive user credentials in your end-user applications.

caution

While Router's security client validation feature is enabled, tokens are tied to the security client they were generated with. Meaning you can't reuse or refresh tokens across different clients.

Requesting a token refresh invalidates your existing access and refresh tokens, returning you a new pair to be used in subsequent requests. Let's finish off with an example on how to do just that.

Request
curl --location --request POST 'http://localhost:3000/authentication/renew' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "refreshToken": "BsKhe3ARhL/FfDfK1REphKkkqQaxRCj/LvvRHOg5wCXCBaUSOwafRHyFYIttaORY/NmHS7NAuT6+knBQegVOwQ=="
      }'
Response
{
  "accessToken": "eyxhbGmZSIsImlhdCI6MTYciOiJIUzI3Mzh0OXVCJ9.RBBF2giwG7OgiWr2HMgHDLMjcR6ddFq2E730Djce71NiIsInR5cCI6IkpMDkmMWJiMTBhDU1NDUyNywiZXhwIjoxNzM0OTU0NTI3fQ.5MDE4yJpZCI6IjYyNDJFjqa7O",
  "refreshToken": "xEuQegVOwQ==KhREphKkkqQaxRCj/LvvRe3ARhL/yFYIttaORY/NmHSFfDfK1HOg5wCXCBaUSOwafRH7NAuT6+k"
}