Document Properties
Kbid295A90
Last Modified02-Nov-2020
Added to KB27-Aug-2020
Public AccessEveryone
StatusOnline
Doc TypeReferences
ProductICM 7.10

Reference - ICM REST API - B2B Front End - Authentication 1.0.0


Product Version

7.10

Product To Version


Status

final

Download Specification 

This API specification is available for download as an Open API 3.0 YAML file: 

API Specification

Introduction

OpenAPI Version: 3.0.1
Authentication Version: 1.0.0

This is Intershop ICM REST API documentation.

This reference lists the REST API for storefront development. The REST API covers features of both, the B2C (SMB - Small and Medium-sized businesses) and the B2B storefront development.
This reference is intended for developers who want to make use of an easy-to-use API when developing frontend solutions.
You can find more information at Intershop Communications. Contact our Intershop experts at Support - Intershop Communications

Introduction

This API is documented in OpenAPI format.

Authentication Protocol: Identity Tokens API

Authentication of REST-Requests

Several API operations require an authenticated user. Intershop ICM REST API supports authentication using:

  • Token endpoint (supports password grant, refresh-token grant, client-authentication grant via basic authentication or bearer token)
  • Basic authentication
  • Header authentication-token

Authentication via Token

Tokens are encoded or signed strings that can be used to authenticate a REST request. Tokens are submitted using the header Authorization containing the word Bearer followed by space and the token string.
Alternatively the header authentication-token containing the user token can be used.

Token Creation via Token Endpoint

The token endpoint is used to create tokens that are used in subsequent requests as authentication token. The user can authenticate using:

  • Username and password
  • Anonymous user
  • Basic authentication
  • Refresh token
    The response will contain a set of tokens that should be used to authenticate subsequent requests. Along with ID- and access-tokens a refresh token is returned. Use the received refresh token to renew expired tokens to authenticate further requests.
    Along with the token, expiration times are given in the token set response. ID and access tokens cannot be used after this expiration time.

Implicit Token Creation

Every REST endpoint supports authentication using basic authentication. To authenticate the client, send the users credentials with the header Authorization that contains the word Basic followed by space and a base64-encoded string username:password.
The response of such a request includes a header authentication-token containing the user token. If the server does not support JWT (JSON Web Token) each response of the REST request will contain the header authentication-token which should replace former tokens since it contains an updated expiration time.

Note:
REST endpoints that support Web-Adapter-cached responses cannot be used for implicit token creation.
If the server supports JWT token as user token, implicit token creation should not be used because the token will not renew.

Token Creation Endpoint

This API can be used to create access and identity tokens which allow clients to securely call protected APIs.
Clients request tokens that can be used in the 'Authorization' header so the server grants access to a particular resource which will be invoked in the context of the encoded user-identity.

Example Use Case

  • Client logs in a user with name and password. The client uses the received ID-token for subsequent requests and stores the refresh-token for further use:
    curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&organization=<ORGANIZATION>"
  • The client renews the ID-token using the refresh-token if it is expired or about to expire:
    Creates a set of tokens based on a refresh token:
    curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>
  • The client logs out the user (this will expire refresh-tokens):
    curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/logout -X PUT -H "Authorization:Basic <REFRESH_TOKEN>"
/token
POST: Creates a new set of tokens.

Description

Token Creation

Creates a set of tokens. The given authorization grant determines for which identity the tokens are created.
Following authorization grants are supported:

Authorization Grants

Anonymous

Creates a set of tokens for an anonymous user. Example call with no form data:

curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST

Alternatively the grant_type can be submitted:

curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=anonymous"

Password

Creates a set of tokens for a user that authenticates via user name and password (and organization, defaults to the sites default organization):

curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&organization=<ORGANIZATION>"

Client Credentials

Creates a set of tokens for a user that authenticates using e.g. basic authentication (user name and password given Base64 encoded , here: admin:!InterShop00!):

curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=client_credentials&organization=<ORGANIZATION>" -H "Authorization:Basic YWRtaW46IUludGVyU2hvcDAwIQ=="

Refresh Token

Creates a set of tokens based on a refresh token:

curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>

Java Method

public com.intershop.beehive.platformrest.resource.auth.TokenRO com.intershop.beehive.platformrest.resource.auth.TokenResource.token(javax.ws.rs.core.MultivaluedMap)

Request Body

Request Parameters

--

Response

200 - OK

TokenRO application/json

400 - Bad Request

401 - Unauthorized

/token/logout
PUT: Logs out the current user.

Description

Logs out the current user. All (refresh) tokens issued for this user will expire and invalidated.

Java Method

public void com.intershop.beehive.platformrest.resource.auth.TokenResource.logout()

Request Body

--

Request Parameters

--

Response

204 - No Content

401 - Unauthorized

Captcha API

/captcha
GET: get captcha code

Description

Responds with script snippet containing CAPTCHA challenge.
Workflow:

  • Send a request to a protected resource.
  • Detect the status 401 Authorization required.
  • Determine the authentication scheme and the necessary parameters.
  • Display the CAPTCHA a human user can solve.
  • Re-send the request including the CAPTCHA challenge and solution.
    At least on CAPTCHA service must be configured as enabled for the application/site. Otherwise the resource will return an error.

Java Method

public java.lang.String com.intershop.sellside.rest.common.capi.resource.CaptchaResource.getCaptchaCode()

Request Body

--

Request Parameters

--

Response

200 - OK

500 - Internal Server Error

response headers will include required fields:
RequiredFields: recaptcha_challenge_field,recaptcha_response_field

Credentials API

/customers/{CustomerKey}/users/{CustomerItemUserKey}/credentials/login
PUT: Update login

Description

Updates the login of the currently logged in user with a new one.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerLoginItemResource.updateLogin(com.intershop.sellside.rest.common.capi.resourceobject.CustomerLoginRO)

Request Body

CustomerLoginRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

possible values for header error-key:
- customer.credentials.missing_fields.error
- customer.credentials.invalid_fields.error

401 - Unauthorized

/customers/{CustomerKey}/users/{CustomerItemUserKey}/credentials/password
PUT: Update password

Description

Updates the password of the currently logged in customer with a new one.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)

Request Body

CustomerPasswordRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

possible values for header error-key:
- customer.credentials.missing_fields.error
- customer.credentials.invalid_fields.error

401 - Unauthorized

/customers/{CustomerKey}/users/{CustomerItemUserKey}/credentials/question
PUT: Update security question

Description

Updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client could get the list of possible keys from /securiry/questions resource.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerSecurityQuestionItemResource.updateSecurityQuestion(com.intershop.sellside.rest.common.capi.resourceobject.SecurityQuestionRO) throws com.intershop.beehive.core.capi.pipeline.PipeletExecutionException

Request Body

SecurityQuestionRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

/privatecustomers/{CustomerKey}/credentials/login
PUT: Update login

Description

Updates the login of the currently logged in user with a new one.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerLoginItemResource.updateLogin(com.intershop.sellside.rest.common.capi.resourceobject.CustomerLoginRO)

Request Body

CustomerLoginRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

possible values for header error-key:
- customer.credentials.missing_fields.error
- customer.credentials.invalid_fields.error

401 - Unauthorized

/privatecustomers/{CustomerKey}/credentials/password
PUT: Update password

Description

Updates the password of the currently logged in customer with a new one.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)

Request Body

CustomerPasswordRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

possible values for header error-key:
- customer.credentials.missing_fields.error
- customer.credentials.invalid_fields.error

401 - Unauthorized

/privatecustomers/{CustomerKey}/credentials/question
PUT: Update security question

Description

Updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client could get the list of possible keys from /securiry/questions resource.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerSecurityQuestionItemResource.updateSecurityQuestion(com.intershop.sellside.rest.common.capi.resourceobject.SecurityQuestionRO) throws com.intershop.beehive.core.capi.pipeline.PipeletExecutionException

Request Body

SecurityQuestionRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

Identity Provider Configurations API

Identity Provider Configurations End Point

Identity providers are used to authenticate users. Clients can use this endpoint in order to receive all identity providers that are available for an organization.
Typically, this information can be used to enable a user to log on to the ICM back office or the storefront. There might be different types of identity providers. The type local is used for the standard internal ICM user login handling which is most often represented by a login form and completely handled by ICM server.
However, other types include oidc for OpenID Connect compatible providers which can be used for single sign-on scenarios.

Example Usage

The following example shows how to retrieve identity providers for organization Operations:

curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/identityproviderconfigurations/Operations
/identityproviderconfigurations/{organizationKey}
GET: Returns a list of identity provider configurations

Description

This operation returns the identity providers that are available for an organization.

Java Method

public java.util.List com.intershop.beehive.platformrest.resource.identity.IdentityProviderConfigurationResource.getConfigurations(java.lang.String,java.lang.String)

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathorganizationKeystringRequired | The key of organization
in queryproviderTypestringThe provider type. If used only matching configurations will be returned.

Response

200 - OK

Array of IdentityProviderConfigurationRO application/json

404 - Not Found

/identityproviderconfigurations/{organizationKey}/{providerKey}
GET: Returns an identity provider configuration

Description

This operation returns the identity providers that are available for an organization.

Java Method

public com.intershop.beehive.platformrest.resource.identity.IdentityProviderConfigurationRO com.intershop.beehive.platformrest.resource.identity.IdentityProviderConfigurationResource.getConfiguration(java.lang.String,java.lang.String)

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathorganizationKeystringRequired | The key of organization
in pathproviderKeystringRequired | The key of the configuration

Response

200 - OK

IdentityProviderConfigurationRO application/json

404 - Not Found

Personalization API

/personalization
GET: Returns a unique personalization ID based on user credentials

Description

--

Java Method

public com.intershop.sellside.rest.common.capi.resourceobject.PersonalizationRO com.intershop.sellside.rest.common.capi.resource.PersonalizationResource.getPersonalizationInfo()

Request Body

--

Request Parameters

--

Response

200 - OK

PersonalizationRO application/json

401 - Unauthorized

Process ID JSON Web Token API

Identity JSON Web Token Processing

Processes an identity JSON web token. Allows clients to explicitly create users or customers associated with identity providers.

/users/processtoken
POST:

Description

--

Java Method

public javax.ws.rs.core.Response com.intershop.beehive.platformrest.resource.user.UserTokenResource.processIDToken(com.intershop.beehive.platformrest.resource.user.IDTokenRO)

Request Body

IDTokenRO application/json

Request Parameters

--

Response

200 - OK

201 - Created

401 - Unauthorized

Public Keys API

Public Keys

ICM JWT tokens are signed using keys. An asymmetric signature uses a public/private key pair. A signature that was generated with a private key can be verified with the public key.
This API allows clients to get the public keys the server uses.

Examples

Get all public keys:

curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/keys 

---
Example Response:
    {
      "keys": [
        {
          "kty": "OKP",
          "use": "sig",
          "crv": "Ed25519",
          "kid": "FUCsFd.hcIIAAAFzAEx5sJAu",
          "x": "AeasbZjilrI2pnlJ6gH91BbBP_1CdTQl0EaU_Wr1G6Y"
        },
        {
          "kty": "OKP",
          "use": "sig",
          "crv": "Ed25519",
          "kid": "rA.sFd.hIswAAAFzwEp5sJAu",
          "x": "8Vpyz4Y95iZpz88HKh2xtgRgYMh8Rj-4zXpI6LNtJPU"
        }
      ]
    }

Following Java code shows how an ID-token can be parsed and verified:

import java.text.ParseException;
import java.util.Objects;

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.MediaType;

import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.JWSHeader;
import com.nimbusds.jose.crypto.Ed25519Verifier;
import com.nimbusds.jose.jwk.JWK;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jwt.SignedJWT;

/**
 * This example illustrates how to verify an ID-token that was signed using a private key.
 */
public class VerifyTokenExample
{
    /**
     * Verifies a signed token using the JSON web-key from the tokens header.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKinHeader(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()) && null != header.getJWK())
        {
            // get key from header and verify
            return jwt.verify(new Ed25519Verifier(header.getJWK()
                            .toOctetKeyPair()));
        }
        return true;
    }

    /**
     * Verifies a signed token using the JSON web-key resolved by the key URI from the tokens header.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKFromJKU(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()) && null != header.getJWKURL())
        {
            // read the key, URI should be present in claim 'jku'
            String key = ClientBuilder.newClient()
                            .target(header.getJWKURL())
                            .request(MediaType.APPLICATION_JSON_TYPE)
                            .get(String.class);

            // get key from resource and verify
            JWK jwk = JWK.parse(key);

            return jwt.verify(new Ed25519Verifier(jwk.toOctetKeyPair()));
        }
        return true;
    }

    /**
     * Verifies a signed token using the JSON web-key resolved using the 'keys'-endpoint.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKFromKeysWithKidResource(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()))
        {
            // read the key from the keys resource
            String key = ClientBuilder.newClient()
                            .target(getKeysURI())
                            // add key id
                            .path(header.getKeyID())
                            .request(MediaType.APPLICATION_JSON_TYPE)
                            .get(String.class);

            // get key from resource and verify
            JWK jwk = JWK.parse(key);

            return jwt.verify(new Ed25519Verifier(jwk.toOctetKeyPair()));
        }
        return true;
    }

    /**
     * Verifies a signed token using the JSON web-key resolved using the 'keys'-endpoint.
     * 
     * @param idToken the token
     * 
     * @return <code>true</code> if the token is valid, <code>false</code> otherwise
     * @throws ParseException if the token could not the parsed
     * @throws JOSEException
     */
    public boolean verifyTokenWithJWKFromKeysResource(String idToken) throws ParseException, JOSEException
    {
        // parse the token into a SignedJWT
        SignedJWT jwt = SignedJWT.parse(idToken);

        JWSHeader header = jwt.getHeader();

        // can only verify asymmetric key
        if (JWSAlgorithm.EdDSA.equals(header.getAlgorithm()))
        {
            // read the key from the keys resource
            String keys = ClientBuilder.newClient()
                            .target(getKeysURI())
                            .request(MediaType.APPLICATION_JSON_TYPE)
                            .get(String.class);

            // get key from resource and verify
            JWKSet jwkSet = JWKSet.parse(keys);

            JWK jwk = Objects.requireNonNull(jwkSet.getKeyByKeyId(header.getKeyID()),
                            "Could not resolve key with id " + header.getKeyID());

            return jwt.verify(new Ed25519Verifier(jwk.toOctetKeyPair()));
        }
        return true;
    }

    String getKeysURI()
    {
        return "https://localhost/INTERSHOP/rest/WFS/inSPIRED/-/keys/";
    }

}
/keys
GET: Returns public keys

Description

This operation returns a set of public keys as JSON Web key (JWT) that can be used to verify signatures generated by ICM server.

Java Method

public net.minidev.json.JSONObject com.intershop.beehive.platformrest.resource.keys.KeyResource.keySet()

Request Body

--

Request Parameters

--

Response

200 - OK

Array of JSONWebKey application/json
/keys/{keyID}
GET: Returns a public key

Description

This operation returns the public key as JSON Web key (JWT) with the given key id (claim kid).

Java Method

public net.minidev.json.JSONObject com.intershop.beehive.platformrest.resource.keys.KeyResource.key(java.lang.String)

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathkeyIDstringRequired | The key ID

Response

200 - OK

JSONWebKey application/json

404 - Not Found

. A JWT with the given key could not be found. Note that expired keys will be deleted from the system after a certain duration.

Security API

/customers/{CustomerKey}/users/{CustomerItemUserKey}/credentials/password
PUT: Update password

Description

Updates the password of the currently logged in customer with a new one.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)

Request Body

CustomerPasswordRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

possible values for header error-key:
- customer.credentials.missing_fields.error
- customer.credentials.invalid_fields.error

401 - Unauthorized

/customers/{CustomerKey}/users/{CustomerItemUserKey}/credentials/question
PUT: Update security question

Description

Updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client could get the list of possible keys from /securiry/questions resource.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerSecurityQuestionItemResource.updateSecurityQuestion(com.intershop.sellside.rest.common.capi.resourceobject.SecurityQuestionRO) throws com.intershop.beehive.core.capi.pipeline.PipeletExecutionException

Request Body

SecurityQuestionRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey
in pathCustomerItemUserKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

/privatecustomers/{CustomerKey}/credentials/password
PUT: Update password

Description

Updates the password of the currently logged in customer with a new one.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)

Request Body

CustomerPasswordRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

possible values for header error-key:
- customer.credentials.missing_fields.error
- customer.credentials.invalid_fields.error

401 - Unauthorized

/privatecustomers/{CustomerKey}/credentials/question
PUT: Update security question

Description

Updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client could get the list of possible keys from /securiry/questions resource.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerSecurityQuestionItemResource.updateSecurityQuestion(com.intershop.sellside.rest.common.capi.resourceobject.SecurityQuestionRO) throws com.intershop.beehive.core.capi.pipeline.PipeletExecutionException

Request Body

SecurityQuestionRO application/json

Request Parameters

LocationNameFormatDescription
in pathCustomerKeystringRequired | The key or UUID to resolve a single item | Example: ExampleKey

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

/security/password
POST: Reset password of registered user.

Description

If the client submits a valid user ID and secure code then password of the related user will be reset to the provided new password value.
User ID and secure hash code are available in the "Change Password" link of password reminder e-mail, send to the user.

Java Method

public void com.intershop.sellside.rest.common.capi.resource.credentials.PasswordResetResource.resetPassword(com.intershop.sellside.rest.common.capi.resourceobject.PasswordResetRO)

Request Body

PasswordResetRO application/json

Request Parameters

--

Response

204 - No Content

Password reset finished successfully. No content in the response body.

400 - Bad Request

in case when submitted data is missing or invalid.
userID should represent registered and non disabled user in the current application.
Provided secure code should match to the secure code of the related user generated when sending Password Reminder e-mail.
Secure code should not be expired at the time this REST call is made.
New Password provided should match to the password validation rules configured for the current application. Possible values for header error-key:
- customer.credentials.passwordreset.missing_fields.error
- customer.credentials.passwordreset.invalid_fields.error
- customer.credentials.passwordreset.invalid_password.error.PasswordExpressionViolation
- customer.credentials.passwordreset.invalid_password.error.PasswordRecentlyUsed

403 - Forbidden

In case of expired secure code for reset password.

422 - Unprocessable Entity

If for some reason valid new password could not be stored
/security/questions
GET: Get list of security questions

Description

--

Java Method

public com.intershop.sellside.rest.common.capi.resource.credentials.SecurityQuestionListResource$SecurityQuestionsCollectionRO com.intershop.sellside.rest.common.capi.resource.credentials.SecurityQuestionListResource.getSecurityQuestions()

Request Body

--

Request Parameters

--

Response

200 - OK

SecurityQuestionsCollectionRO application/json
/security/reminder
POST: Request password reminder e-mail

Description

If the client submits a login e-mail address, first and last name and the answer to the security question set during the registration then an e-mail will be sent to the customer, or customer's user, containing a link to reset their password.
This feature depends on correctly configured preferences for "Forgotten password" functionality and "SecurityQuestion".

Java Method

public void com.intershop.sellside.rest.common.capi.resource.credentials.PasswordReminderResource.sendPassword(com.intershop.sellside.rest.common.capi.resourceobject.PasswordReminderRO)

Request Body

PasswordReminderRO application/json

Request Parameters

--

Response

200 - OK

400 - Bad Request

in case when submitted data is missing or invalid

500 - Internal Server Error

Request and Response Object Schemata

CustomerLoginRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    Readonly | The type of the object. This is normally a constant that can be used to differentiate objects by their type.
  • "login":
    string
    the login used for authentication | Example: pmiller@test.intershop.de
}
CustomerPasswordRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    Readonly | The type of the object. This is normally a constant that can be used to differentiate objects by their type.
  • "password":
    string
    new password | Example: InterShop00
  • "currentPassword":
    string
    current password | Example: !InterShop00!
}
IDTokenRO application/json{
  • "id_token":
    string
    The base64 encoded identity token | Documentation: JSON Web Token (JWT) | Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  • "options":
    array
    An array of string literals. Processing options
}
IdentityProviderConfigurationRO application/json[
IdentityProviderConfigurationRO: Properties of an identity provider.
{
  • "key":
    string
    The key of this identity provider configuration | Example: uniqueKey
  • "name":
    string
    The name of this identity provider configuration | Example: display name
  • "type":
    string
    The type of this identity provider configuration | Example: local
}
]
JSONWebKey application/json[
JSONWebKey: A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key.
{
  • "kid":
    string
    Key ID parameter.
  • "x":
    string
    The key | Example: MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4
  • "use":
    string
    Public key use parameter | Example: sig
  • "kty":
    string
    Example: YPsXB8rdXix5vwsg1F
  • "crv":
    string
  • "jku":
    string
    JSON Web Key (JWK) set URL | Example: https://localhost/INTERSHOP/rest/WFS/inSPIRED/-/keys/
}
]
PasswordReminderRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    Readonly | The type of the object. This is normally a constant that can be used to differentiate objects by their type.
  • "email":
    string
    Required | the email to send the reminder to | Example: goosen@test.intershop.de
  • "firstName":
    string
    the first name of the recipient. Required in case Security question feature is enabled. | Example: Gerhardt
  • "lastName":
    string
    the last name of the recipient. Required in case Security question feature is enabled. | Example: Goosen
  • "answer":
    string
    the answer to the security question. Required in case Security question feature is enabled. | Example: Snoopy
}
PasswordResetRO application/json{
  • "userID":
    string
    Required | The unique ID of the user which password will be set. Provided in the Password Reminder e-mail message. | Example: mt4KAEsByeIAAAFtwuREkERx
  • "secureCode":
    string
    Required | Unique security code used for verification. Provided in the Password Reminder e-mail message. | Example: bfd51c73-0e2a-46e1-a3e4-b977a001ae9a
  • "password":
    string
    Required | The new password to be set for the related user. | Example: mynewpassword2019
}
PersonalizationRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: Personalization
  • "pgid":
    string
    the personalization group identifier (pgid) of the personalization object | Example: HLgg8Yus9qBSR0rCuy4DMI9n0000ys
}
SecurityQuestionRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: SecurityQuestion
  • "text":
    string
    the text of the security question | Example: What is your pet's name?
  • "key":
    string
    the key of the security question | Example: account.security_question.pet_name.text
}
SecurityQuestionsCollectionRO application/json{
  • "pageable":
    string
    The pageable ID
  • "total":
    integer
    The pageable amount total | Format: int32
  • "offset":
    integer
    The pageable offset | Format: int32
  • "amount":
    integer
    The pageable amount | Format: int32
  • "elements":
    array
    An array of SecurityQuestionRO objects. The list of elements
    [
    SecurityQuestionRO:
    {
    • "name":
      string
      The name of an element.
    • "type":
      string
      The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: SecurityQuestion
    • "text":
      string
      the text of the security question | Example: What is your pet's name?
    • "key":
      string
      the key of the security question | Example: account.security_question.pet_name.text
    }
    ]
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type.
  • "sortKeys":
    array
    An array of string literals. The keys to sort for
  • "name":
    string
    The name of an element.
}
TokenRO application/json{
  • "id_token":
    string
    ID token
  • "access_token":
    string
    the access token
  • "refresh_token":
    string
    Refresh token. The refresh token can be used to create a new token set.
  • "expires_in":
    integer
    Expiration time of access and ID token | Format: int64
  • "refresh_expires_in":
    integer
    Expiration time of the refresh token | Format: int64
  • "token_type":
    string
    Type of the access and ID token. If the tokens are encoded as JWT, the type is 'bearer', 'user' otherwise. | Example: bearer | Possible Values: beareruser
}

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets