Password authentication

Use this flow if you want to simply authenticate your users with email and password credentials, and you do not want to configure a 3rd-party provider.

Password Reset

Keel provides built-in requestPasswordReset and resetPassword actions on the Identity model for handling password resets.

Requesting a Reset

Call the requestPasswordReset action with the user's email and an optional redirectUrl:

curl --request POST \
  --url 'http://localhost:8000/api/json/requestPasswordReset' \
  --header 'Content-Type: application/json' \
  --data '{"email": "user@example.com", "redirectUrl": "https://app.example.com/reset-password"}'

If the email matches an existing identity, Keel sends a password reset email containing a link to the redirect URL with a token query parameter. If no identity is found, the request succeeds silently to prevent email enumeration.

The redirectUrl is optional. If omitted, Keel uses the first URL configured in passwordResetUrl. If provided, it must match one of the configured URLs.

Resetting the Password

After the user clicks the link, extract the token from the query string and call the resetPassword action:

curl --request POST \
  --url 'http://localhost:8000/api/json/resetPassword' \
  --header 'Content-Type: application/json' \
  --data '{"token": "{{reset_token}}", "password": "newSecurePassword123"}'

Reset tokens are single-use. Once a password has been successfully reset, the same token cannot be used again.

Getting Access Tokens

Signing up and authenticating an existing user both takes place by calling the /auth/token endpoint with the password grant.

curl --request POST \
  --url 'http://localhost:8000/auth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data username={{email}} \
  --data password={{password}}

If you are successfully authenticated, the token endpoint will respond with HTTP 200 and an application/json response body.

HTTP 200

{
  "access_token": "{{keel_access_token}}",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "{{keel_refresh_token}}",
  "identity_created": false
}

Perform authenticated requests to your Keel APIs

After authenticating, proceed to use the access token you have received to perform authenticated requests to your Keel APIs. This is done by including the access token (prefixed with Bearer) in the Authorization header of the request.

curl --request POST \
  --url 'http://localhost:8000/api/json/searchAuthors' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...' \
  --data '{ "where": { "name": { "startsWith": "Bob" } } }'

ID Token Tokens