soul

Authentication / Authorization

These endpoints are for Soul in the Auth mode. For that you need to enable auth mode by setting the AUTH=true environment variable or using the -a argument when starting a Soul server.

1. Obtain an access token

To obtain an access token call /auth/token/obtain/ endpoint with POST method.

curl -v --request POST \
  --url http://localhost:8000/api/auth/token/obtain \
  --header 'Content-Type: application/json' \
  --data '{
	"fields": {
		"username": "damien",
		"password": "strongpass"
	}
}'

Response

...
< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
...

You can see that when login is successful, Soul sets two cookies one for the access token and the other for the refresh token.

{
  "message": "Success",
  "data": {
    "userId": 1
  }
}

Body Params

• fields containing username and password e.g.

"fields": {
		"username": "damien",
		"password": "strongpass"
}

Here’s how the jwt access token payload looks like:

{
  "subject": "accessToken",
  "username": "damien",
  "userId": 1,
  "isSuperuser": "false",
  "roleIds": [1],
  "iat": 1717427688,
  "exp": 1717463688
}

2. Refresh token

To refresh and obtain a new access token call /auth/token/refresh/ endpoint with GET method.

curl -v http://localhost:8000/api/auth/token/refresh \
  --cookie 'refreshToken=<jwt-refresh-token>'

Response

...
< Set-Cookie: accessToken=<jwt-access-token>; Path=/; HttpOnly
< Set-Cookie: refreshToken=<jwt-refresh-token>; Path=/; HttpOnly
...

There you get a new token pair

{
  "message": "Success",
  "data": {
    "userId": 1
  }
}

Cookies

• refreshToken the refresh token that you acquired before

3. Change password

To change your account password call /auth/change-password/ endpoint with PUT method.

curl --request PUT \
  --url http://localhost:8000/api/auth/change-password \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "currentPassword": "strongpass",
      "newPassword": "anotherstrongpass"
    }
  }' \
  --cookie 'accessToken=<jwt-access-token>'

Response

{
  "message": "Password updated successfully",
  "data": {
    "id": 1,
    "username": "damien"
  }
}

Body Params

• fields containing currentPassword and newPassword e.g.

"fields": {
  "currentPassword": "strongpass",
  "newPassword": "anotherstrongpass"
}

Cookies

• accessToken the access token that you acquired before

4. Logout

In order to logout from your account e.g. remove access and refresh cookies and also revoke your refresh token (access token lifetime is very short and doesn’t need to be revoked) call /auth/logout/ endpoint with GET method.

curl http://localhost:8000/api/auth/logout \
  --cookie 'accessToken=<jwt-access-token>' \
  --cookie 'refreshToken=<jwt-refresh-token>'

Response

{
  "message": "Logout successful"
}

Cookies

• accessToken the access token that you acquired before
• refreshToken the refresh token that you acquired before

This site is open source. Improve this page.