In the following example, REST calls based on the simple self-registration flow are given.
User Data Registration Step (to enter user profile)
This request starts the self-registration of a user. Since no flow is selected explicitly, the default flow is started.
Step 1 - HTTP request- User Data Registration Step
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/
{
"surname" : "Doe",
"email" : "john.doe@ergon.ch",
"town" : "Zürich",
"birthdate" : "1970-10-01"
}A successful response will return a value of USER_DATA_REGISTRATION_REQUIRED if the call was successful but a call to continue would fail. Use the validate call to list all validation issues.
Step 1 - HTTP response - User Data Registration Step
copy
HTTP/1.1 200 OK
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T08:43:48.356Z"
},
"data": {
"type": "user-self-registration.session",
"id": "509880836941347711",
"attributes": {
"nextStep": "USER_DATA_REGISTRATION_REQUIRED"
}
}
}Since the given name is mandatory but was missing from the previous call, another call to the /data/ REST API is required.
Step 1 - HTTP request - User Data Registration Step
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/
{
"givenname" : "John"
}A successful response will return a value of USER_DATA_REGISTRATION_POSSIBLE if the call was successful and a call to continue will be successful as well.
Step 1 - HTTP response - User Data Registration Step
copy
HTTP/1.1 200 OK
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T08:44:33.047Z"
},
"data": {
"type": "user-self-registration.session",
"id": "509880836941347711",
"attributes": {
"nextStep": "USER_DATA_REGISTRATION_POSSIBLE"
}
}
}Continue
This request is required to move the flow one step ahead.
Step 1 - HTTP request - continue
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/continue
Since we already know that the validation was successful, the response should always be a 200 OK.
Step 1 - HTTP response - continue
copy
HTTP/1.1 200 OK
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T08:50:39.232Z"
},
"data": {
"type": "user-self-registration.session",
"id": "509880836941347711",
"attributes": {
"nextStep": "EMAIL_OTP_REQUIRED"
}
}
}Username Generation Step
Step 2 is non-interactive and does not require any REST calls to be executed.
Email Verification Step
When the Email Verification Step is started, it first generates a message and sends it to the channel verification target (i.e. the email address) to be verified.
Email Message
Dear John Doe
Please confirm the registration of the email address john.doe@virtinc.com with by entering the code
973 183
in the corresponding input field of the registration form.
Best regards, your Virtinc team
In the user interface, the user is required to enter the code provided in the message to be entered.
Step 3 - HTTP request - Email Verification Step
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/verification/email/otp/check/
{
"otp" : "973183"
}Step 3 - HTTP response - Email Verification Step
copy
HTTP/1.1 200 OK
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T08:51:19.268Z"
},
"data": {
"type": "user-self-registration.session",
"id": "509880836941347711",
"attributes": {
"nextStep": "USER_DATA_REGISTRATION_REQUIRED"
}
}
}User Data Registration Step (to set the password)
Step 4 - HTTP request - User Data Registration Step
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/password/
{
"password" : "password0"
}Step 4 - HTTP response - User Data Registration Step
copy
HTTP/1.1 200 OK
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T08:51:44.996Z"
},
"data": {
"type": "user-self-registration.session",
"id": "509880836941347711",
"attributes": {
"nextStep": "USER_DATA_REGISTRATION_POSSIBLE"
}
}
}Continue
This request is required to move the flow one step ahead.
Step 4 - HTTP request - continue
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/continue
Since we already know that the validation was successful, the response should always be a 200 OK.
Step 4 - HTTP response - continue
copy
HTTP/1.1 200 OK
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T08:52:02.237Z"
},
"data": {
"type": "user-self-registration.session",
"id": "509880836941347711",
"attributes": {}
}
}User Persisting Step
After the continue, the User Persisting Step will be executed automatically.
Error response example
In this example request, the birthdate attribute contains incorrectly formatted input.
HTTP request - user data registration step with incorrect data
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/
{
"surname" : "Doe",
"givenname" : "John",
"email" : "jdoe@ergon.ch",
"town" : "Zürich",
"birthdate" : "1.1.1970"
}In case of an error (in the example below the formatting of the birthdate was incorrect) a detailed error message is returned:
HTTP response failure - User Data Registration Step
copy
HTTP/1.1 400 Bad Request
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T09:01:47.225Z",
"nextStep": "USER_DATA_REGISTRATION_REQUIRED"
},
"errors": [
{
"code": "VALIDATION_FAILED",
"source": {
"pointer": "/birthdate"
},
"meta": {
"type": "jsonapi.metadata.validation.error",
"detail": "WRONG_FORMAT"
}
}
]
}Validation example
The validate REST call is strictly speaking optional, but it is rather helpful for a GUI client to provide the end-user with information on why a particular set of data was rejected by the registration flow validation.
Note: it is possible to issue this call as the first call in the flow. This would allow the GUI to dynamically indicate to the user, which fields are mandatory and must be filled without hardcoding and before the user submits the form.
HTTP Request: validate
copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/validate
The validation returns all "errors" that must be addressed before a continue call to the next step in the flow is possible.
Note: a 200 OK return code implies that the validation was successful and the step can be continued. A 400 Bad Request is returned to indicate issues with validation.
HTTP Response: validate
copy
HTTP/1.1 400 Bad Request
{
"meta": {
"type": "jsonapi.metadata.document",
"timestamp": "2018-12-12T08:55:38.700Z",
"nextStep": "USER_DATA_REGISTRATION_REQUIRED"
},
"errors": [
{
"code": "VALIDATION_FAILED",
"source": {
"pointer": "/email"
},
"meta": {
"type": "jsonapi.metadata.validation.error",
"detail": "REQUIRED"
}
},
{
"code": "VALIDATION_FAILED",
"source": {
"pointer": "/givenname"
},
"meta": {
"type": "jsonapi.metadata.validation.error",
"detail": "REQUIRED"
}
},
{
"code": "VALIDATION_FAILED",
"source": {
"pointer": "/surname"
},
"meta": {
"type": "jsonapi.metadata.validation.error",
"detail": "REQUIRED"
}
}
]
}