Reference Library
  1. Introduction
  2. Rest Service - challenges
  3. Rest Service - checkpassword
  4. Rest Service - forgottenpassword
  5. Rest Service - health
  6. Rest Service - profile
  7. Rest Service - randompassword
  8. Rest Service - setpassword
  9. Rest Service - signing/form
  10. Rest Service - statistics
  11. Rest Service - status
  12. Rest Service - verifyotp
  13. Rest Service - verifyresponses



Introduction

This system has a set of RESTful web APIs to facilitate 3rd party application development.

Authentication

All web services are authenticated using basic access authentication utilizing the standard Authorization header.

The username portion of the authentication can either be a fully qualified LDAP DN of the user, or a username string value which the application will search for the user

Additionally, the application must be configured in such away to allow web service calls. Not all functions may be enabled. Some operations which involve a third party (other then the authenticated user) may require additional permissions configured within the application.

Standard JSON Response

All JSON encoded responses are presented using a standard JSON object: Example: 
{
   "error": true,
   "errorCode": 5004,
   "errorMessage": "Authentication required.",
   "errorDetail": "5004 ERROR_AUTHENTICATION_REQUIRED",
   "data": {}
}
field type description
errorbooleanfalse if the operation was successfull
errorCodefour-digit numberapplication error code
errorMessagestringLocalized error message string
errorDetailstringError Number, Error ID and debugging detail message if any, English only
successMessagestringLocalized success message string
dataobjectRequested data

Example REST Client

End User Module Example REST Client

Rest Service - challenges

url /pwm/public/rest/challenges
GET Method
Description Retrieve users stored challenges. Location of read responses is determined by the application configuration. This interface cannot be used to read NMAS stored responses.
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Parameter answers
Nameanswers
RequiredOptional
Locationquery string
ValueBoolean indicating if answers (in whatever format stored) should be returned in the result.
Defaultfalse
Parameter helpdesk
Namehelpdesk
RequiredOptional
Locationquery string
ValueBoolean indicating if helpdesk answers should be returned in the result.
Defaultfalse
Parameter username
Nameusername
RequiredOptional
Locationquery string
ValueOptional username or ldap DN of a user on which to perform the operation
DefaultAuthenticating user (if LDAP)
Example 1
Request 
GET /pwm/public/rest/challenges HTTP/1.1
Accept: application/json
Location: en
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Response 
{
  "error": false,
  "errorCode": 0,
  "data": {
    "challenges": [
      {
        "challengeText": "What is the name of the main character in your favorite book?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false
      },
      {
        "challengeText": "What is the name of your favorite teacher?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false
      },
      {
        "challengeText": "Who is your favorite author?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false
      },
      {
        "challengeText": "What street did you grow up on?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false
      }
    ],
    "minimumRandoms": 2
  }
}
Example 2
Request 
GET /pwm/public/rest/challenges?answers=true&helpdesk=true HTTP/1.1
Accept: application/json
Accept-Language: en
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Response 
{
  "error": false,
  "errorCode": 0,
  "data": {
    "challenges": [
      {
        "challengeText": "What is the name of the main character in your favorite book?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false,
        "answer": {
          "type": "SHA1_SALT",
          "answerHash": "Q8zzP3Tyo5i4IKDaT1stkbh/m80=",
          "salt": "3ZxfxbmlF4yp2KfDOAkDvMP9EgGOgkPL",
          "hashCount": 100000,
          "caseInsensitive": true
        }
      },
      {
        "challengeText": "What is your least favorite film of all time?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false,
        "answer": {
          "type": "SHA1_SALT",
          "answerHash": "rzBiYIvZvdbbCrXgoUDtqKdwrh0=",
          "salt": "RoaMiuCNBXZjK9vqeV7xYdRsKdL0D1wi",
          "hashCount": 100000,
          "caseInsensitive": true
        }
      },
      {
        "challengeText": "What street did you grow up on?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false,
        "answer": {
          "type": "SHA1_SALT",
          "answerHash": "3KhvS0YLV3qAso1QmtZzGiv36s0=",
          "salt": "a27P1ke4Z4qchdcjepIjSikF8JKNa50U",
          "hashCount": 100000,
          "caseInsensitive": true
        }
      },
      {
        "challengeText": "Who is your favorite author?",
        "minLength": 4,
        "maxLength": 200,
        "adminDefined": true,
        "required": false,
        "answer": {
          "type": "SHA1_SALT",
          "answerHash": "N8VLF4UN6+7IvPN/LVwSfZhCjm4=",
          "salt": "oBulI5Y6u7JgrItFPbu8vMEJqhe3lq8o",
          "hashCount": 100000,
          "caseInsensitive": true
        }
      }
    ],
    "helpdeskChallenges": [
      {
        "challengeText": "Helpdesk Question 1",
        "minLength": 2,
        "maxLength": 100,
        "adminDefined": true,
        "required": true,
        "answer": {
          "type": "HELPDESK",
          "answerText": "Answer 1",
          "hashCount": 0,
          "caseInsensitive": false
        }
      },
      {
        "challengeText": "Helpdesk Question 2",
        "minLength": 2,
        "maxLength": 100,
        "adminDefined": true,
        "required": true,
        "answer": {
          "type": "HELPDESK",
          "answerText": "Answer 2",
          "hashCount": 0,
          "caseInsensitive": false
        }
      }
    ],
    "minimumRandoms": 2
  }
}
POST Method
Description Set users stored challenge/response set
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
Parameter username
Nameusername
RequiredOptional
Locationquery string or json body
ValueOptional username or ldap DN of a user on which to perform the operation
DefaultAuthenticating user (if LDAP)
Parameter challenges
Namechallenges
RequiredRequired
Locationjson body
ValueList of challenge objects including answers with an answerText property. Retrieve challenge objects using the challenges service to discover the proper object formatting. The question object data must match precisely the question object received from the challenges service so that the answer can be applied to the correct corresponding question. This includes each parameter of the question object.
Defaultn/a
Example 1
Request 
Accept-Language: en
POST /pwm/public/rest/challenges HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "challenges":[
      {
         "challengeText":"What is the name of the main character in your favorite book?",
         "minLength":4,
         "maxLength":200,
         "adminDefined":true,
         "required":false,
         "answer":{
            "answerText":"Answer 1"
         }
      },
      {
         "challengeText":"What is your least favorite film of all time?",
         "minLength":4,
         "maxLength":200,
         "adminDefined":true,
         "required":false,
         "answer":{
            "answerText":"Answer 2"
         }
      },
      {
         "challengeText":"What street did you grow up on?",
         "minLength":4,
         "maxLength":200,
         "adminDefined":true,
         "required":false,
         "answer":{
            "answerText":"Answer 3"
         }
      },
      {
         "challengeText":"Who is your favorite author?",
         "minLength":4,
         "maxLength":200,
         "adminDefined":true,
         "required":false,
         "answer":{
            "answerText":"Answer 4"
         }
      }
   ],
   "helpdeskChallenges":[
      {
         "challengeText":"Helpdesk Question 1",
         "minLength":2,
         "maxLength":100,
         "adminDefined":true,
         "required":true,
         "answer":{
            "answerText":"Answer 5"
         }
      },
      {
         "challengeText":"Helpdesk Question 2",
         "minLength":2,
         "maxLength":100,
         "adminDefined":true,
         "required":true,
         "answer":{
            "answerText":"Answer 6"
         }
      }
   ],
   "minimumRandoms":2
}
Response 
{
  "error": false,
  "errorCode": 0,
  "successMessage": "Your secret questions and answers have been successfully saved.  If you ever forget your password, you can use the answers to these questions to reset your password."
}
Example 2
Request 
POST /pwm/public/rest/challenges HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "challenges":[
      {
         "challengeText":"Who is your favorite author?",
         "minLength":4,
         "maxLength":200,
         "adminDefined":true,
         "required":false,
         "answer":{
            "answerText":"Answer 1"
         }
      }
   ],
   "minimumRandoms":1,
   "username":"otherUser",
}
Response 
{
  "error": false,
  "errorCode": 0,
  "successMessage": "Your secret questions and answers have been successfully saved.  If you ever forget your password, you can use the answers to these questions to reset your password."
}
DELETE Method
Description Clear users saved responses
Authentication Required
Accept Header application/json
Parameter username
Nameusername
RequiredOptional
Locationquery string
ValueOptional username or ldap DN of a user on which to perform the operation
DefaultAuthenticating user (if LDAP)
Example 1
Request 
DELETE /pwm/public/rest/challenges?username=user1234 HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Response 
 {
   "error": false,
   "errorCode": 0,
   "successMessage": "Your secret questions and answers have been successfully saved.  If you ever forget your password, you can use the answers to these questions to reset your password."
 }

Rest Service - checkpassword

url /pwm/public/rest/checkpassword
POST Method
Description Check a password value(s) against user policy
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
application/x-www-form-urlencoded
Parameter password1
Namepassword1
RequiredRequired
Locationquery string, json body, or form body
ValuePassword value
Defaultn/a
Parameter password2
Namepassword2
RequiredRequired
Locationquery string, json body, or form body
ValuePassword confirmation value
Defaultn/a
Parameter username
Nameusername
RequiredOptional
Locationquery string, json body, or form body
ValueOptional username or ldap DN of a user on which to perform the operation
DefaultAuthenticating user (if LDAP)
Example 1
Request 
POST /pwm/public/rest/checkpassword HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "password1":"newPassword",
   "password2":"newPasswOrd"
}
Response 
{
  "error": false,
  "errorCode": 0,
  "data": {
    "version": 2,
    "strength": 37,
    "match": "NO_MATCH",
    "message": "New password is using a value that is not allowed",
    "passed": false,
    "errorCode": 4034
  }
}
Example 2
Request 
POST /pwm/public/rest/checkpassword HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

password1=dsa32!dabed&password2=dsa32!dabed&username=user1234
Response 
{
   "error":false,
   "errorCode":0,
   "data":{
      "version":2,
      "strength":21,
      "match":"MATCH",
      "message":"New password accepted, please click change password",
      "passed":true,
      "errorCode":0
   }
}

Rest Service - forgottenpassword

url /pwm/public/rest/forgottenpassword
POST Method
Description A multi-stage endpoint suitable for anonymous clients to implement a forgotten password module. Clients will call this service repeatedly until the process is completed. The following stages will be processed (some may be repeated or omitted based on policy and configuration):
  • IDENTIFICATION
  • METHOD_CHOICE
  • TOKEN_CHOICE
  • VERIFICATION
  • ACTION_CHOICE
  • NEW_PASSWORD
  • COMPLETE

Each invocation of this service (except the first) requires a state parameter and form data. The state parameter is received from the previous invocation (or empty on the first call). It is the client's responsibility to maintain this state value throughout the process. If the state is invalid or expired, a new state will be generated by the server and the process restarted. The client can clear the state at any time to restart the sequence. Once the COMPLETE stage is reached, no further steps are possible and a new sequence will require discarding the state.

Each response from the service will include form data with one or more rows that will guide the client to create a UI for the user. Form fields are generally of type 'text' or 'select'. In the case of 'select' form fields, a 'selectOptions' value will include the possible values for the row. The next request to the server should include the state and the form data values for each form field. A form label and message is also included for display to the user.

The response from the service will include additional data of the 'stage' and 'method' (if appropriate). These values are informational and intended to aid the client in displaying an appropriate UI to the end user.

Errors can indicate syntax, operational, or internal errors. In most cases form data will also be included along with the error so that the user has an opportunity to attempt the operation again.

See also: End User Module Example REST Client
Authentication Not Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
Example 1
Request 
POST /pwm/public/rest/forgottenpassword HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json

{}
Response 
{
   "error":false,
   "errorCode":0,
   "data":{
      "stage":"IDENTIFICATION",
      "form":{
         "formRows":[
            {
               "name":"cn",
               "minimumLength":1,
               "maximumLength":64,
               "type":"text",
               "required":true,
               "label":"Username",
               "selectOptions":{
               }
            }
         ],
         "label":"Forgotten Password",
         "message":"If you have forgotten your password, follow the prompts to reset your password."
      },
      "state":"NzJKin4agg3QXx9q0EBSeZ1UTTYhxVCTjwshrkyj.H4sIAAAAAAAAAAEDAfz-UFdNLkdDTTEQ5Rd8CuZrpUD4VXcp8aHuHE5FvUNrG9R_uILHRhxnt30XjKX_eKe1qClcM_I-SoKabNX6xIrJgkXx2N0Ic64uTKriexiGihMJ1SmNrG6YfKVkhtAPLsQieiqcfjgJTAnVkSlol4FFzOqgqVvpx8FIJz6TACZYG2l4aZ3JXfCGhu32Uq6iKVHkDs_skkndZmLIQsb4sLbUN-JVVwxwyzyzyqNccSHyeOPoWaIWeenjjzBa_lfGx0SM5U3Y_g3taMBx2TwyZzj2QOtQ5eUyaYQ_4P-SyGL5tQZCiXgb8FDwhZvHLuUKw289vWX8vBg7TX5cUj3Ki348AQpltLe1K6kDAQAA"
   }
}
Example 2
Request 
POST /pwm/public/rest/forgottenpassword HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json

{
   "state":"yKtUhNohePx3zE02SmnWuJqArRlrxeb7jwsh9758.H4sIAAAAAAAAAAEDAfz-UFdNLkdDTTEQ5Rd8CuZrpUD4VXcp8aHuFQglychy7rHCsdBpaizdfE09tI-hs4aoP_GNo6bPahgM1vopVprxz_zsY0uAHxQvVdzLm79AxDAgDobrsGVxNq2GvGjE8DkrjT1SBNjdVmTMm6d80toJgMdCvjJvaMiLmDbiRI80blo5jxjwNXisTZcJAqJGxc-bbvtdgzl2sGmJijc2e4eAX4zf77b2BsyOnTfwkNdXMXlR4jnjis0yWeXK_WI0YCoOwWnE96VkQ1Rl9feBHfWLptuOAD2qDZ_rqs5k8ImUztPBmm_XHzs1K3giQE3jxOK3IxFT-onSBY-OMiCCUNaX7uuPhWRfsxIDAQAA",
   "form":{
      "cn":"asmith"
   }
}
Response 
{
   "error":false,
   "errorCode":0,
   "data":{
      "stage":"VERIFICATION",
      "method":"ATTRIBUTES",
      "form":{
         "formRows":[
            {
               "name":"challenge0",
               "minimumLength":6,
               "maximumLength":199,
               "type":"text",
               "required":false,
               "label":"What is the name of the main character in your favorite books?",
               "selectOptions":{

               }
            },
            {
               "name":"challenge1",
               "minimumLength":6,
               "maximumLength":199,
               "type":"text",
               "required":false,
               "label":"What is the name of your favoraite teacher?",
               "selectOptions":{

               }
            }
         ],
         "label":"Forgotten Password",
         "message":"Please answer the following questions. If you answer these questions correctly, you will then be able to reset your password."
      },
      "state":"yKtUhNohePx3zE02SmnWuJqArRlrxeb7jwsh9758.H4sIAAAAAAAAAAGcBWP6UFdNLkdDTTEQ5Rd8CuZrpUD4VXcp8aHuFgQsvTdvwJK3sRGhSZiSN9iUjeYDGBOmy0YsA573uvLxh1rUIPpJrFnmlbKKLUrM0JdzrktheFrdAvEhPKz3yrMGO7gmNqAcWToXxr6a81EBFRyPrOn3Yb2Jo7D9a-Pm8MFFZhNqrlsgqtH_UVvdC2qe-unxE54GT2GnNooL6SN2FUdskfvt7Jr8nld4hI9bhneRKRu9hXT8xdJ-fAXI7MYvGZtLs-JamVBgMrddVmhwxC3ehWEWslVKQqPpAx_3fAtdnum2IfcMuZAntTL3bypQ8HZ8Rad76uhDKiy2rngIVvd3qasslzxM1PhkAgPPT2aUsWULTxAPZYXMW6lX5ajSwV4rW48X5oN43g1PW-WLWMMmEn6kM3LbHRnWi7mVN1K7t2JvNqXxHGLQUQOfkCa7A4CVi2hoiCU6Cw88yXtRSA6unpdFSGziAH7EfLoYuG0jgqLHls_L1iJVb3ZVaSGZ0vHpzDuVqhbOq7p3NII7wtEIvDGlejp546f8zAwFIeWqX7UwsdRH3dOZ54UJkbLuV3Gm6q-E81ED_ZgZznuxZmZAenUYyo_qOO9XYGjKWDN3daCamkh2ybs7-HymLct2NsAR_1eLpdxeIQ4-TCa0pjA7waRqNwyMSlcrQfwXpOgvdvUBuIyK7hel3wvXkbF_zcPTCzrStb2f6XNcgEJ-p6zoN5uyTKV96eYzEQTYMvJkabq49aeqn3NItRJvOHP0yXWr3B1il1wdLD_6rK_CaUCunKUuTj5CF_yea7U_Wm7crGYgtFOcrcBlzGn2omvFSoJw3Sx79XlimVBNQLeOj37hTlhVmQ-6uaVmJk4ozfgPaPTUY3TIgLJSFtOkJb4AV6XZeFYb1dWgjdqW0TuurHOa04-JsXP-KhrkkX_b5ej8Wf17HdJyHXSf731tnp0QVYfoyIvsU0j6q1ZXmSxpoL7RrFIKx11tv6TT355vFtgkiXdXJKgNeLffil85p9quv8YCYW5hck35O3V41pEDE6BZ2RpLjU3akZnAqZSydieICDaznjdyxL-8qd1AQuZQwWntige1GrfHnGGEVvNFWcLTscdsbSnp8tzE2QNpFw45RAFgX5xJXfrla7ioDbFocvixqnhrKYA9Dr3IYYnyuOhx1U1Md5n7cGrcGc8i1tcgvqH1AclHbJZuP1jRAE009t72nPG45pLOgVoHF4hTHkxnvIId7sNsJxetcYP62gffgi3rdwmxJNcVeMZkKhJWA-syyPgcObRxK3s4OSf1wsyQTQ_-orY54izTLLSVMLG70MczUHx3Vm0er8131OMhtP0SRai0NcCT9gV-R4ig6P47EEu2hP1JBd5A9LWPpRSYaSIAL7K4gDhf-reHqH_V3-Q6MUDrHQJDtZAyYADE3qY7mWu2Xkw54khNxlEsgu3BpJmGFB_D6isG_QPbXtkjLgyanw5tcAUtljWnNeAN98B-sTrvUBP8UGSSJwLfHuWh7-HDskb9CWVxLEBf2mlphd4Cx-zXwMy5vS181NYSjsMfzHGCck3Jo5ynaQYa0KMAFw3wGkGkFssI0KTB3bUTW5lCM4GcQsXgPtI0f1G9uye6TVdsdgVVTzKUyaBlTrH_iel9oRwk2iJDVRiz4Sg9iLcw_DFK5Man4AOfuqdRvHqlc7DJ0nhDyxYcnIQc_yPPZA9ic5qoFCv5lMg_ABerHNwutg0Gdq6Ff4yER52KekY39bgHtJPpjs8W6ORUa_6G-HVGsCZeg-RQks9iq6OTgmWxzv4vdto7QP6snvaDGLmgInV-Ie1_g3g4fgcMRKFxy8q-jGYU9Y_TLtc0y47voLj8H-auWv9mAJo0Ztp43aPs7XujpmTJyqPdPBzwxl_Ey6sF9rzzjuchz1Avnf1_0B4JR8UynAUAAA=="
   }
}

Rest Service - health

url /pwm/public/rest/health
GET Method
Description Read the health of the application
Authentication Not Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
text/plain
Parameter refreshImmediate refreshImmediate=true
Indicates if the server should refresh the health status before calling this service. Only available if logged in with administrative rights.
Example 1
Request 
GET /pwm/public/rest/health HTTP/1.1
Accept-Language: en
Accept: application/json
Response 
{
   "error":false,
   "errorCode":0,
   "data":{
      "timestamp":"Mar 27, 2013 6:15:04 PM",
      "overall":"CONFIG",
      "records":[
         {
            "status":"CONFIG",
            "topic":"Configuration",
            "detail":"LDAP Directory -> LDAP Proxy Password strength of password is weak (21/100); increase password length/complexity for proper security"
         },
         {
            "status":"CONFIG",
            "topic":"Configuration",
            "detail":"PWM is currently in configuration mode. Anyone accessing this site can modify the configuration without authenticating. When ready, restrict the configuration to secure this installation."
         },
         {
            "status":"CONFIG",
            "topic":"Configuration",
            "detail":"Security -> Require HTTPS setting should be set to true for proper security"
         },
         {
            "status":"GOOD",
            "topic":"Java Platform",
            "detail":"Java platform is operating normally"
         },
         {
            "status":"GOOD",
            "topic":"LDAP",
            "detail":"All configured LDAP servers are reachable"
         },
         {
            "status":"GOOD",
            "topic":"LDAP",
            "detail":"LDAP test user account is functioning normally"
         },
         {
            "status":"GOOD",
            "topic":"LocalDB",
            "detail":"LocalDB and related services are operating correctly"
         }
      ]
   }
}
Example 2
Request 
GET /pwm/public/rest/health&refreshImmediate=true HTTP/1.1
Accept-Language: en
Accept: text/plain
Response 
GOOD

Rest Service - profile

url /pwm/public/rest/profile
GET Method
Description Retrieve users profile data
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Parameter username
Nameusername
RequiredOptional
Locationquery string
ValueOptional username or ldap DN of a user on which to perform the operation
DefaultAuthenticating user (if LDAP)
Example 1
Request 
GET /pwm/public/rest/profile HTTP/1.1
Accept: application/json
Accept-Language: en
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Response 
{
  "error": false,
  "errorCode": 0,
  "data": {
    "profile": {
      "title": "Genious",
      "description": "Genious User",
      "telephoneNumber": "555-1212"
    },
    "formDefinition": [
      {
        "name": "telephoneNumber",
        "minimumLength": 3,
        "maximumLength": 15,
        "type": "text",
        "required": true,
        "confirmationRequired": false,
        "readonly": false,
        "labels": {
          "": "Telephone Number"
        },
        "regexErrors": {
          "": ""
        },
        "description": {
          "": ""
        },
        "selectOptions": {

        }
      },
      {
        "name": "title",
        "minimumLength": 2,
        "maximumLength": 15,
        "type": "text",
        "required": true,
        "confirmationRequired": false,
        "readonly": false,
        "labels": {
          "": "Title"
        },
        "regexErrors": {
          "": ""
        },
        "description": {
          "": ""
        },
        "selectOptions": {

        }
      },
      {
        "name": "description",
        "minimumLength": 1,
        "maximumLength": 50,
        "type": "hidden",
        "required": false,
        "confirmationRequired": false,
        "readonly": false,
        "labels": {
          "": "Descr"
        },
        "regexErrors": {
          "": ""
        },
        "description": {
          "": ""
        },
        "selectOptions": {

        }
      }
    ]
  }
}
POST Method
Description Set profile data
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
Example 1
Request 
POST /pwm/public/rest/profile HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "profile":{
      "title":"Genious",
      "description":"Genious User",
      "telephoneNumber":"555-1212"
   }
}
Response 
{
   "error":false,
   "errorCode":0,
   "successMessage":"Your user information has been successfully updated."
}

Rest Service - randompassword

url /pwm/public/rest/randompassword
GET Method
Description Read a single random password value
Authentication Optional
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header text/plain
Parameter username username=user1234
Optional username or ldap DN of a user on which to base the random password generation on. The user's policies will be applied to the random generation.
Parameter strength strength=50
Optional number (0-100) specifying the minimum strength of the generated password.
Parameter minLength minLength=5
Optional number specifying the minimum length of the generated password.
Parameter chars chars=ABCDEFG12345690
Optional list of charachters to use for generating the password.
Example 1
Request 
GET /pwm/public/rest/randompassword HTTP/1.1
Accept-Language: en
Accept: text/plain
Response 
cLi2mbers
POST Method
Description Read a single random password value
Authentication Optional
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
Parameter username username=user1234
Optional username or ldap DN of a user on which to base the random password generation on. The user's policies will be applied to the random generation.
Parameter strength strength=50
Optional number (0-100) specifying the minimum strength of the generated password.
Parameter minLength minLength=5
Optional number specifying the minimum length of the generated password.
Parameter chars chars=ABCDEFG12345690
Optional list of charachters to use for generating the password.
Example 1
Request 
GET /pwm/public/rest/randompassword HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json

{
    "chars":"abcdefg123456",
    "strength":5
}
Response 
{
   "error":false,
   "errorCode":0,
   "data":{
      "password":"bbf535"
   }
}

Rest Service - setpassword

url /pwm/public/rest/setpassword
POST Method
Description Set a user's password value
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
application/x-www-form-urlencoded
Parameter username username=user1234
Optional username or ldap DN of a user on which to set the password.
Parameter password password=newPassword
Required value of new password.
Parameter random random=true
Generate a random password (when random=true, no value for 'password' should be supplied.
Example 1
Request 
POST /pwm/public/rest/setpassword HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "password": "newPassword"
}
Response 
cLi2mbers

Rest Service - signing/form

url /pwm/public/rest/signing/form
POST Method
Description Pre-sign (and encrypt) form data for injection into an PWM user form. PWM user forms do not permit a remote application to POST data directly to them through a browser. Instead this signing/form REST api can be used to pre-sign and then submit data to the form.
Usage After the form data is signed, it can be submitted as part of a request to PWM using the signedForm parameter and the value is the encoded data value returned in the result. Values expire after a period of time.

Example:
/pwm/public/newuser?signedForm=xxx
Authentication Required. Use a named secret username:secret value defined at Settings ⇨ Web Services ⇨ REST Services ⇨ Web Service Non-LDAP Users and Passwords.
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
application/x-www-form-urlencoded
Example 1
Request 
POST /pwm/public/rest/signing/form HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic c2VjcmV0MTpwYXNzd29yZA==

{
  "givenName":"John",
  "sn":"Doe"
}
Response 
{
  "error": false,
  "errorCode": 0,
  "data": "H4sIAAAAAAAAAAFxAI7_UFdNLkdDTTEQz1yn2zvAMXknwMu2NNpJLpkD4uwWmFQXq80VZH4cxAXYXLmWq05rNTaBJJ3D8PVLElZA8a_XSdzltDku0kwIkmwTW0D7EYXwFId0EA-mTGygsFuLF--BJLxcwyw5jKkAO2miy-w_f2rPiSaycQAAAA=="
}

Rest Service - statistics

url /pwm/public/rest/statistics
GET Method
Description Read system statistics
Authentication Required unless otherwise configured
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
Parameter days
Namedays
RequiredOptional
Locationquery string
ValueNumber of history days to return in result.
Default7
Parameter version
Namehelpdesk
RequiredOptional
Locationquery string
ValueNumber indicating API version to use.
Default2
Example 1
Request 
GET /pwm/public/rest/statistics?days=30 HTTP/1.1
Accept-Language: en
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Response 
{
   "error":false,
   "errorCode":0,
   "data":{
     "error": false,
     "errorCode": 0,
     "data": {
       "labels": [
         {
           "name": "ACTIVATED_USERS",
           "label": "Activated Users",
           "type": "INCREMENTER",
           "description": "Number of users that have successfully completed the user activation process."
         }
       ],
       "eventRates": [
         {
           "name": "AUTHENTICATION_DAY",
           "value": "3.000"
         }
       ],
       "current": [
         {
           "name": "ACTIVATED_USERS",
           "value": "0"
         }
       ],
       "cumulative": [
         {
           "name": "ACTIVATED_USERS",
           "value": "15"
         }
       ],
       "history": [
         {
           "name": "DAILY_2018_206",
           "date": "2018-07-25",
           "year": 2018,
           "month": 6,
           "day": 25,
           "daysAgo": 0,
           "data": [
             {
               "name": "ACTIVATED_USERS",
               "value": "0"
             }
           ]
         }
       ]
     }
   }
}
Actual response is much larger, this example is truncated to show only one instance of each data element.

Rest Service - status

url /pwm/public/rest/status
GET Method
Description Read users status data
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Parameter username username=user1234
Optional username or ldap DN of a user of which to read the status.
Example 1
Request 
GET /pwm/public/rest/status HTTP/1.1
Accept: application/json
Accept-Language: fr
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Response 
{
  "error": false,
  "errorCode": 0,
  "data": {
    "userDN": "cn=user,ou=users,o=data",
    "userID": "user",
    "userEmailAddress": "[email protected]",
    "passwordLastModifiedTime": "Apr 1, 1970 6:59:43 PM",
    "requiresNewPassword": false,
    "requiresResponseConfig": false,
    "requiresUpdateProfile": false,
    "requiresInteraction": true,
    "passwordStatus": {
      "expired": false,
      "preExpired": false,
      "violatesPolicy": false,
      "warnPeriod": false
    },
    "passwordPolicy": {
      "MaximumNumeric": "0",
      "MinimumSpecial": "0",
      "AllowLastCharSpecial": "true",
      "ADComplexity": "false",
      "RegExNoMatch": ".*%.*",
      "AllowSpecial": "true",
      "MaximumSpecial": "0",
      "MinimumLowerCase": "0",
      "MinimumUnique": "0",
      "MinimumNumeric": "0",
      "MinimumLength": "2",
      "DisallowedValues": "test\npassword",
      "CaseSensitive": "true",
      "RegExMatch": "",
      "DisallowCurrent": "true",
      "AllowFirstCharSpecial": "true",
      "MinimumLifetime": "0",
      "ExpirationInterval": "0",
      "UniqueRequired": "false",
      "MaximumSequentialRepeat": "0",
      "AllowNumeric": "true",
      "AllowFirstCharNumeric": "true",
      "EnableWordlist": "false",
      "MaximumLength": "64",
      "DisallowedAttributes": "sn\ncn\ngivenName",
      "AllowLastCharNumeric": "true",
      "PolicyEnabled": "true",
      "MaximumUpperCase": "0",
      "MinimumUpperCase": "0",
      "ChangeMessage": "sdsadasd\ndsadsadsa\nddsadsa\ndsadsad\nsadasda",
      "MaximumLowerCase": "0"
    },
    "passwordRules": [
      "Le mot de passe est sensible à la casse",
      "Doit comporter au moins 2 caractère",
      "Ne peut contenir l’une des valeurs suivantes:  test password",
      "Ne doit pas contenir une partie de votre nom ou  identifiant."
    ]
  }
}

Rest Service - verifyotp

url /pwm/public/rest/verifyotp
POST Method
Description Validate supplied one time password against a user's stored secret.
Authentication Required
Accept Header application/json
Content-Type Header application/json
Parameter username username=user1234
Optional username or ldap DN of a user on which to verify the one time password.
Parameter token token=123456
One time password to be verified.
Example 1
Request 
POST /pwm/public/rest/verifyotp HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "token": 123456
}
Response 
{
    "error": false,
    "errorCode": 0,
    "successMessage": "The operation has been successfully completed.",
    "data": false
}

Rest Service - verifyresponses

url /pwm/public/rest/verifyresponses
POST Method
Description Validate supplied challenge response answers against a user's stored responses. Note this service will not work properly if the user's responses are stored only in the NMAS repository.
Authentication Required
Accept-Language Header en
The request will be processed in the context of the specified language
Accept Header application/json
Content-Type Header application/json
Parameter username
Nameusername
RequiredOptional
Locationquery string or json body
ValueOptional username or ldap DN of a user on which to verify the responses
DefaultAuthenticating user (if LDAP)
Parameter challenges
Namechallenges
RequiredRequired
Locationjson body
ValueList of challenge objects including answers with an answerText property. Retrieve challenge objects using the challenges service to discover the proper object formatting. The question object data must match precisely the question object received from the challenges service so that the answer can be applied to the correct corresponding question. This includes each parameter of the question object.
Defaultn/a
Example 1
Request 
POST /pwm/public/rest/verifyresponses HTTP/1.1
Accept-Language: en
Accept: application/json
Content-Type: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
   "username":"user1234",
   "challenges":[
      {
         "challengeText":"What is the name of the main character in your favorite book?",
         "minLength":4,
         "maxLength":200,
         "adminDefined":true,
         "required":false,
         "answer":{
            "answerText":"Answer 1"
         }
      },
      {
         "challengeText":"What is your least favorite film of all time?",
         "minLength":4,
         "maxLength":200,
         "adminDefined":true,
         "required":false,
         "answer":{
            "answerText":"Answer 2"
         }
      }
   ]
}
Response 
{
    "error": false,
    "errorCode": 0,
    "successMessage": "The operation has been successfully completed.",
    "data": true
}