Credential API (v1)

The endpoint is protected and allows end users(CIAM or admin) to get the primary email. The regular users must have 'credential:primary-email:get' scope and admin users must have the 'credential:primary-email:admin:get' scope in order to view another user's primary email.

When this API is called, it triggers the following process:

• The email address is added to the user's profile if it wasn't already included. If the email address is added, it will get the type 'home' by default.
• A verification email is sent to the requested primary email address containing a verification link.
• When the recipient clicks on the link to confirm, he is asked to login to make sure that the person that has access to the email box is the same person as the person that is the legitimate user of the identity. If the recipient successfully logs in, the user's primary email address is updated to the requested value.

Multiple calls to this endpoint can be done:

• Every call will generate a new email, so this API-call can be (mis)used to have an end user re-confirm his primary email address.

A user's profile can have multiple email addresses:

• The list of all emails for a user can be obtained through the iWelcome SCIM API. The credential API reveals only the ones that are primary or are requested to become primary.
• Until the 'new' email address is confirmed by the end user, the primary email address of the end user will not be changed; it will still have the 'old' value.

If the authenticated user has the scope 'credential:primary-email:post', it can create a new primary email request. An admin user can create a new primary email request only if the scope 'credential:primary-email:admin:post' is present.

When a user's email address needs to be verified, it sends a link to the user's email address. When that link is clicked on, the user needs to login (if not already) before this protected endpoint can be invoked to confirm the email address and make it primary. The provided access token must have the 'credential:primary-email:post' scope. The reason for protecting this endpoint is to make sure that the user that clicks on the confirmation link, is the legitimate user of the account. This may not be in the case in the following scenario's:

• The end-user made a typo when entering his 'new' primary e-mail request; he may have entered d.johnsson@mydomain.com instead of d.johnson@mydomain.com. If Dan Johnsson clicks on the link, he has in fact taken-over the account and Dave Johnson has lost access to his account because logging in with the original email address (e.g. davejohnson@mydomain.com) and password is no longer working.
• An end-user may have left a device on which he is logged-in 'open' and a malicious person can change the e-mail address unnoticed. Again, the legitimate user would loose access to the account.

iWelcome considers this as a best practice in the context of 'security and privacy by design'. Customers who prefer a more user-friendly process without the need for logging in, can consider using the "/credential/v1/public/primary-email-confirmation" endpoint instead.

The confirmation has the following effects on the attribute value metadata (AVM) of the new email address:

• currency.LastVerification is set to current timestamp
• accuracy.Validation is set to valid
• accuracy.VerificationLevel is set to 1
• accuracy.VerificationMethod is set to Proof of Possession
• accuracy.Verifier is set to Provider
• provenance.provider is set to the configured data controller for the segment
• provenance.pedigree is set to self-asserted

Customers need to request iWelcome to expose this endpoint, which by default is not the case, since usage does not follow the principle of 'security by design'. The benefit of this endpoint above the protected version is that the end-user will get a better user-experience since he doesn't have to login when confirming the new e-mail address.

This endpoint is the same as the /credential/v1/primary-email-request endpoint, but without the need for the end-user to authenticate himself. As a consequence, a 401 response is not applicable.

The endpoint is protected and allows end users(CIAM or admin) to get the current primary phone number. The regular users must have 'credential:primary-phonenumber:get' scope and admin users must have the 'credential:primary-phonenumber:admin:get' scope in order to view another user's primary phone number.

When this API is called, it triggers the following process:

• The phone number is added to the user's profile if it wasn't already included. If the phone number is added, it will get the type 'home' by default. If the phone number is already verified, it will be made primary without sending an SMS for validation.
• A SMS is sent to the requested primary phone number containing a OTP token.
• When calling /primary-phone-number-confirmation with the previously obtained OTP token, the phone number becomes primary.

Multiple calls to this endpoint can be done:

• Every call will generate a new SMS, so this API-call can be (mis)used to have an end user re-confirm his primary phone number.

A user's profile can have multiple phone numbers:

• The list of all phone numbers for a user can be obtained through the iWelcome SCIM API. The credential API reveals only the ones that are primary or are requested to become primary.
• Until the 'new' phone number is confirmed by the end user, the primary phone number of the end user will not be changed; it will still have the 'old' value.

If the authenticated user has the scope 'credential:primary-phonenumber:post', it can create a new primary phone number request. An admin user can create a new primary phone number request only if the scope 'credential:primary-phonenumber:admin:post' is present.

When a user's phone number needs to be verified, it sends a SMS with the OTP token to the user's phone number. When that token is provided to this endpoint along with an access token containing the 'credential:primary-phonenumber:post' scope, the user's phone number will become primary.

The confirmation has the following effects on the attribute value metadata (AVM) of the new phone number:

• currency.LastVerification is set to current timestamp
• accuracy.Validation is set to valid
• accuracy.VerificationLevel is set to 1
• accuracy.VerificationMethod is set to Proof of Possession
• accuracy.Verifier is set to Provider
• provenance.provider is set to the configured data controller for the segment
• provenance.pedigree is set to self-asserted

When this API is called, it triggers the following process:

• The phone number is added to the user's profile if it wasn't already included. If the phone number is added, it will get the type 'home' by default. If the phone number is already verified, it will be made primary without sending an SMS for validation.
• A SMS is sent to the requested primary phone number containing a OTP token.
• When calling /primary-phone-number-confirmation with the previously obtained OTP token, the phone number becomes primary.

Multiple calls to this endpoint can be done:

• Every call will generate a new SMS, so this API-call can be (mis)used to have an end user re-confirm his primary phone number.

A user's profile can have multiple phone numbers:

• The list of all phone numbers for a user can be obtained through the iWelcome SCIM API. The credential API reveals only the ones that are primary or are requested to become primary.
• Until the 'new' phone number is confirmed by the end user, the primary phone number of the end user will not be changed; it will still have the 'old' value.

If the authenticated user has the scope 'credential:primary-phonenumber:post', it can create a new primary phone number request. The authenticated user id will be used for performing the operation. An admin user can create a new primary phone number request only if the scope 'credential:primary-phonenumber:admin:post' is present. If this scope is present, then the request must contain the user id, otherwise the request will fail with 400 Bad Request, indicating that the user_id is not valid.

When a user's phone number needs to be verified, it sends a SMS with the OTP token to the user's phone number. When the authenticated user is verifying it's own phone number, the scope 'credential:primary-phonenumber::post' is required. If an admin is performing this operation on behalf of the user, the scope 'credential:primary-phonenumber:admin:post' is needed. If this scope is present, then the request must contain the user id, otherwise the request will fail with 400 Bad Request, indicating that the user_id is not valid. Assuming the access token has the correct scope assigned, the user's phone number will become primary.

The confirmation has the following effects on the attribute value metadata (AVM) of the new phone number:

• currency.LastVerification is set to current timestamp
• accuracy.Validation is set to valid
• accuracy.VerificationLevel is set to 1
• accuracy.VerificationMethod is set to Proof of Possession
• accuracy.Verifier is set to Provider
• provenance.provider is set to the configured data controller for the segment
• provenance.pedigree is set to self-asserted

An endpoint to retrieve profile data from any social provider. The access_token needs to have the scope: 'credential:identity-link:profile:post'.

An endpoint to initiate the account linking process before redirecting the user to the (social) identity provider for login. The access_token needs to have one of the following scopes: 'credential:identity-link:post' is needed when the authenticated user is initiating its own identity link and scope 'credential:identity-link:admin:post' is needed when the initiated link is made by an application. This endpoint returns parameter values that must be sent to the OAuth specified /authorize endpoint at the external identity provider):

• The value of the 'id' must be passed on to the identity provider as value for the 'state' parameter, as specified by OAuth.
• The value of the 'nonce' must simply be used as a 'nonce' parameter.

Method used to activate the identity link. Invoking this method changes the status of the identity-link from 'inactive' or 'pending' to 'active'. The access_token needs to have one of the following scopes: 'credential:identity-link:patch' is needed when the authenticated user is activating its own IDP and scope 'credential:identity-link:admin:patch' is needed when the link is activated by an application. In this situation, the user id of the identity link with 'linkId' is set to the one from the payload.

Endpoint used to link a (social) identity to the authenticated user. The 'state' parameter that the OAuth identity provider provided in the call-back must be used. The access_token needs to have one of the following scopes: 'credential:identity-link:put' is needed when the authenticated user is linking its own IDP and scope 'credential:identity-link:admin:put' is needed when the link is made by an application. In this situation, the user id of the identity link with 'authorizationCode' is set to the one from the payload.

Endpoint used to unlink a (social) account from the authenticated user. The access_token needs to have one of the following scopes 'credential:identity-link:delete' is needed when the authenticated user is deleting its own identity link and to delete a link of somebody else the access_token needs to have scope 'credential:identity-link:admin:delete' as authorisation.

This is a protected endpoint and allows end users(CIAM or admin) to set their passwords. Admin users must have the 'credential:password:manager' scope in order to set another user's password.

Obtain information about the user's password.

The Set Password API is a protected endpoint and allows end-users(CIAM) to change their password. For security reasons, the authenticated user needs to provide either one of: * current password * ID-token