Password API

The Password API allows end users in your team to update their passwords.

First, create a password recovery email, which includes a link (and recovery token) specific to this end user. Then, the end user can follow the link to a web page in Epicenter where they can reset their password. Alternatively, you can also use the Password API with this recovery token to update the password directly.

The Password API supports the following HTTP methods:

• POST: Sending a password recovery email, with token
• POST: Setting a new password

POST: Sending a password recovery email

Use the Password API with the recovery endpoint to send a password recovery email (including link and recovery token) to the end user.

---

Method: POST

URI: /v2/password/recovery

Headers:

• Content-Type: application/json

Body: JSON object with the fields:

• userName (required): the end user who wants to reset their password
• account (required): the Team ID this end user belongs to
• projectFullName (optional): the name of the project; appears in the body of the email, defaults to "Forio Epicenter"
• subject (optional): the subject of the email; defaults to "Forio Epicenter Password Reset"
• redirectUrl (required): where the end user should be directed after clicking on the link in the password recovery email and resetting their password; must be absolute

Return Status:

• 200: successful response
• 403: if there is no email address in the user record for userName
• 404: if there is no user whose userName matches the userName in the request

Return Body: A message indicating that the password recovery email has been sent.

---

Example:

curl -X POST \
    'https://api.forio.com/v2/password/recovery' \
    --header 'Content-Type: application/json' \
    --data '{"userName": "endUser@acmesimulations.com", "account": "acme-simulations", "projectFullName": "Supply Chain Simulation", "subject": "Please reset your Supply Chain password", "redirectUrl": "https://forio.com/app/acme-simulations/supply-chain-game"}'

Example Response:

{ "message": "Notification sent." }

Example Email Sent to End User: (based on the example request above)

Subject: Please reset your Supply Chain password
To: endUser@acmesimulations.com
From: support@forio.com
Body:
    You have requested a password reset for the user endUser@acmesimulations.com in Supply Chain Simulation. 

    If you did not initiate this request, please ignore this email.

    To reset your password, please click the following link: https://forio.com/epicenter/recover/<password recovery token>

Notes:

• The result of this request is that a password recovery token is generated and automatically included in the email to the end user.

• Note that the recovery token is not part of the response to the API call.

• However, the recovery token can be used in another POST request to reset the password.

• The token is valid exactly once in the 24 hours after it is created.

POST: Setting a new password

Use the Password API with the set endpoint and a valid password recovery token to set an end user's password.

---

Method: POST

URI: /v2/password/set/{recovery token}

Headers: Content-Type: application/json Body: JSON object with the fields:

• password: the new password

Return Status:

• 200: successful response

• 404: if the recovery token is no longer valid

• Return Body: JSON object with the user access token for this end user: access token, refresh token, and expiration, based on the updated password.

---

Example:

curl -X POST \
    'https://api.forio.com/v2/password/set/eb7e3b4c-776b-4472-c4a9-c51f22496fc8' \
    --header 'Content-Type: application/json' \
    --data '{"password": "newPassw0rd"}'

Example Response:

{
    "refresh_token": "eyJqdGkiOiJlOWNlYTVmZ",
    "access_token": "eyJhbGciOiJSUzI1NiJ9",
    "expires": 43199,
    "account": "acme-simulations",
    "userName": "endUser@acmesimulations.com",
    "userId": "8754ebdc-ef44-4098-9cf7-89d25088d39f",
    "redirectUrl": "https://forio.com/app/acme-simulations/supply-chain-game"
}

Notes:

• Each recovery token is valid exactly once in the 24 hours after it is created.