Document Properties
Kbid
U29770
Last Modified
23-Nov-2023
Added to KB
25-Jan-2021
Public Access
Everyone
Status
Online
Doc Type
References
Product
ICM 7.10
Reference - Authentication REST API 1.2.1 (ICM 7.10)
Document View


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

References

The following page lists available REST APIs for ICM 7.10 and their version dependencies:

API Specification

Introduction
OpenAPI Version: 3.0.1
Authentication Version: 1.2.1

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 a 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 with:

  • Username and password
  • Anonymous user
  • Basic authentication
  • Refresh token

The response contains a set of tokens that should be used to authenticate subsequent requests. Along with identity (ID) tokens 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 specified in the token set response. ID tokens and access tokens can no longer be used after this expiration time.

Implicit Token Creation

Every REST endpoint supports authentication using basic authentication. To authenticate the client, send the user's credentials with the Authorization header, which contains the word Basic followed by a space and a base64-encoded string username:password.
The response of such a request includes a header authentication-token which contains the user token. If the server does not support JSON Web Token (JWT), 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 tokens as user tokens, implicit token creation should not be used because the token will not renew.

Token Creation Endpoint

This API can be used to create access tokens and ID tokens that clients can use 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

  • A user is logged in via the client with user 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, see 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 user is logged out by the client (this causes the refresh tokens to expire):
    curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/logout -X PUT -H "Authorization:Basic <REFRESH_TOKEN>"
/logout
PUT: Logs out the current user

Description

This operation logs out the current user associated with the specified authentication token (as header). All (refresh) tokens issued for this user will expire and become invalid.

Java Method

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

Request Body

--

Request Parameters

--

Response

204 - No Content

401 - Unauthorized - The user to logout cannot be determined.

/token
POST: Creates a new set of tokens

Description

Token Creation

This operation creates a set of tokens. The kind of generated token(s) can be configured using the property intershop.cartridges.rest.tokenKind which supports the following values:

The given authorization grant determines for which identity the tokens are created. The following authorization grants are supported:

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, by default the site's 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 are specified in base64 encoding: <USERNAME:PASSWORD>, 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 - The given authorization grant is invalid.

401 - Unauthorized - The user to logout cannot be determined or is unauthorized.

/token/logout
PUT: Revokes a token

Description

This operation revokes the token given as authentication token (as header). This is equivalent with the Logout endpoint, so it logs out the current user. All (refresh) tokens issued for this user will expire and become invalid.

Java Method

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

Request Body

--

Request Parameters

--

Response

204 - No Content

401 - Unauthorized - The user to logout cannot be determined.

Captcha API
/captcha
GET: Returns CAPTCHA code

Description

This operation responds with a script snippet containing a 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: Updates login

Description

This operation 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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item
in pathCustomerItemUserKeystringExampleKeyRequired | The key or UUID to resolve a single item

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: Updates password

Description

This operation 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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item
in pathCustomerItemUserKeystringExampleKeyRequired | The key or UUID to resolve a single item

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: Updates security question

Description

This operation updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client can get the list of possible keys from the /security/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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item
in pathCustomerItemUserKeystringExampleKeyRequired | The key or UUID to resolve a single item

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

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

Description

This operation 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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item

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: Updates password

Description

This operation 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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item

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: Updates security question

Description

This operation updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client can get the list of possible keys from the /security/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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

ID JSON Web Token Processing API

This section covers the processing of an identity JSON web token. This allows clients to explicitly create users or customers associated with identity providers.

/users/processtoken
POST: Processes an identity JSON web token

Description

Identity Token Processing

This operation processes an identity JSON web token. The claims will be used to update or create user profiles.
The token can be passed either as bearer token using the Authorization header or as property id_token in JSON body data.

User Creation and Updating

Identities or users encoded in the JSON web token are mapped to ICM user profiles or customer instances.
The sub along with the issuer of the token is used as mapping key. Dependent on options, the following handling takes place:

  • For non-mapped identities, a new user is created and claims are mapped to profile, address or credential properties,
  • Profile of already mapped identities are updated using the claims of the token.

User Profile Mapping

The claims of the identity token are mapped as follows:

Claim Profile Property
title title
given_name firstName
middle_name lastName (start)
family_name lastName (end)
nickname nickName
email email
birthdate birthdate
locale locale

The preferred user name is computed from the following claims by default (if set):

  • preferred_username
  • (unique_name)
  • name
  • sub

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 - The token has been accepted for an already existing user. If requested, the user data will be updated based on the claims encoded in the identity JSON web token.

UserRO application/json

201 - Created - A new user profile has been created based on the claims encoded in the identity JSON web token.

UserRO application/json

401 - Unauthorized - The token is missing, empty or the token's content is invalid.

403 - Forbidden - The user account is disabled.

409 - Conflict - The token contains a user, but the user cannot be found in the system.

422 - Unprocessable Entity - HTTP code 422 is returned if:
1. The attribute options in the request body contains CREATE_USER, CREATE_CUSTOMER or CREATE_SMB_CUSTOMER
The user/customer does not exist and has to be created
configuration property intershop.authentication.<organizationKey>.selfAdministrationPolicy (for the user's organization) does not contain CREATE
1. The attribute options in the request body contains UPDATE
The user/customer does exist
configuration property intershop.authentication.<organizationKey>.selfAdministrationPolicy (for the user's organization) does not contain UPDATE

Identity Provider Configurations API

This section covers operations related to identity provider configurations.

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 the 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 the 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

LocationNameFormatDefaultExampleDescription
in pathorganizationKeystringRequired | The ID of the 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}/selfadministrationpolicy
GET: Returns the self-administration policy (entries) of an organization.

Description

This operation returns the self-administration policy of an organization. The self-administration policy describes which kinds of profile changes are allowed for a user belonging to a certain organization when those changes are triggered by the user itself (self-administration).

Possible values are NONE or (XOR) any combination of: CREATE, UPDATE, DELETE.

Semantics:

  • NONE: no changes allowed (this value overrules all other values)
  • CREATE: user can create a profile on his/her own
  • UPDATE: user can update his/her profile on his/her own
  • DELETE: user can delete his/her profile on his/her own

Java Method

public java.util.Set com.intershop.beehive.platformrest.resource.identity.IdentityProviderConfigurationResource.getSelfAdminisrationPolicy(java.lang.String)

Request Body

--

Request Parameters

LocationNameFormatDefaultExampleDescription
in pathorganizationKeystringRequired | The ID of the organization

Response

200 - OK

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

LocationNameFormatDefaultExampleDescription
in pathorganizationKeystringRequired | The ID of the organization
in pathproviderKeystringRequired | The ID 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

Public Keys API

This section covers operations that allow clients to retrieve public keys used by the server.

ICM JWT tokens are signed following the RFC7515: the private part of a key pair is used to create a signature for the actual token payload. So the payload's validity (payload is unmodified and the origin is known) can be checked using the public key.
The ICM creates key pairs on demand: whenever a token is generated and there's no key stored (in memory) which is not timed out.
Attention: before requesting at least 1 token there will be no public key available (see resource https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token).

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"
        }
      ]
    }

Parse and Verify an ID Token

The 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

LocationNameFormatDefaultExampleDescription
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: Updates password

Description

This operation 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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item
in pathCustomerItemUserKeystringExampleKeyRequired | The key or UUID to resolve a single item

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: Updates security question

Description

This operation updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client can get the list of possible keys from the /security/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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item
in pathCustomerItemUserKeystringExampleKeyRequired | The key or UUID to resolve a single item

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

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

Description

This operation 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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item

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: Updates security question

Description

This operation updates the security question of the currently logged in customer. The key of the security question should be submitted.
A client can get the list of possible keys from the /security/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

LocationNameFormatDefaultExampleDescription
in pathCustomerKeystringExampleKeyRequired | The key or UUID to resolve a single item

Response

204 - No Content

400 - Bad Request

401 - Unauthorized

/security/password
POST: Resets password of a registered user

Description

This operation allows for resetting the password of a registered user. If the client submits a valid user ID and secure code, the password of the related user will be reset to the new password value provided.
User ID and secure hash code are available in the "Change Password" link of the password reminder e-mail sent 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 the submitted data is missing or invalid.
The userID should represent a registered and non-disabled user in the current application.
The provided secure code should match the related user's secure code generated when sending the password reminder e-mail.
The secure code should not be expired at the time this REST call is made.
The new password provided should match 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 an expired secure code for the password reset.

422 - Unprocessable Entity If for some reason a valid new password could not be stored.

/security/questions
GET: Returns a list of security questions

Description

This operation returns a list of all available security questions.

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: Requests password reminder e-mail

Description

This operation allows for sending a password reminder e-mail. If the client submits a login e-mail address, first and last name as well as the answer to the security question set during the registration, 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" 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 the 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 element. This is normally a constant that can be used to differentiate elements 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 element. This is normally a constant that can be used to differentiate elements by their type.
  • "password":
    string
    The new password | Example: InterShop00
  • "currentPassword":
    string
    The 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
  • "secure_user_ref":
    object
    A SecureUserRefRO object.
    {
    • "user_id":
      string
    • "secure_code":
      string
    }
  • "options":
    array
    An array of string literals. The following ID token options are available:
    ||Option||
    |CREATE_USER|
    |CREATE_CUSTOMER|
    |CREATE_SMB_CUSTOMER|
    |UPDATE|
    |MOVE_TO_TARGET_USER| | Example: CREATE_USER,UPDATE,MOVE_TO_TARGET_USER
}
IdentityProviderConfigurationRO application/json[
IdentityProviderConfigurationRO: This resource holds properties of an identity provider.
{
  • "key":
    string
    The ID 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 element. This is normally a constant that can be used to differentiate elements 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 the security question feature is enabled. | Example: Gerhardt
  • "lastName":
    string
    The last name of the recipient. Required in case the security question feature is enabled. | Example: Goosen
  • "answer":
    string
    The answer to the security question. Required in case the security question feature is enabled. | Example: Snoopy
}
PasswordResetRO application/json{
  • "userID":
    string
    Required | The unique ID of the user whose password will be reset. 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 element. This is normally a constant that can be used to differentiate elements 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 element. This is normally a constant that can be used to differentiate elements 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 element. This is normally a constant that can be used to differentiate elements 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 element. This is normally a constant that can be used to differentiate elements 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
    Can be used to create a new token set
  • "expires_in":
    integer
    Access and ID token life time in seconds | Format: int64
  • "refresh_expires_in":
    integer
    Refresh token life time in seconds | 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
}
UserRO application/json{
  • "name":
    string
    The name of an element
  • "type":
    string
    Readonly | The type of the element. This is normally a constant that can be used to differentiate elements by their type.
  • "id":
    string
  • "title":
    string
    The personal title, like Ms., Mr. | Example: Mr.
  • "firstName":
    string
    The given name (also known as a personal name, first name, forename) of the person represented by this user | Example: Peter
  • "secondName":
    string
  • "lastName":
    string
    The surname (also known as a family name, last name) of the person represented by this user | Example: Merkel
  • "secondLastName":
    string
  • "gender":
    string
  • "birthday":
    string
    Date of birth of the person represented by this user in format MM/dd/yyyy | Example: 12/24/1998
  • "businessPartnerNo":
    string
    ID uniquely identifying the user in the context of the customer. | Example: PMerkel
  • "login":
    string
}
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.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.