This API specification is available for download as an Open API 3.0 YAML file:
The following page lists available REST APIs for ICM 7.10 and their version dependencies:
Several API operations require an authenticated user. Intershop ICM REST API supports authentication using:
authentication-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.
The token endpoint is used to create tokens that are used in subsequent requests as authentication token. The user can authenticate using:
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.
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>"
/logout
Logs out the current user as associated with the given authentication token (as header). All (refresh) tokens issued for this user will expire and invalidated.
public void com.intershop.beehive.platformrest.resource.auth.TokenResource.logout()
204 - No Content
401 - Unauthorized
/token
Creates a set of tokens. The given authorization grant determines for which identity the tokens are created.
Following authorization grants are supported:
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"
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>"
Creates a set of tokens for a user that authenticates using e.g. basic authentication (user name and password given Base64 encoded
curl http://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/token -X POST -d "grant_type=client_credentials&organization=<ORGANIZATION>" -H "Authorization:Basic YWRtaW46IUludGVyU2hvcDAwIQ=="
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>
public com.intershop.beehive.platformrest.resource.auth.TokenRO com.intershop.beehive.platformrest.resource.auth.TokenResource.token(javax.ws.rs.core.MultivaluedMap)
200 - OK
400 - Bad Request
401 - Unauthorized
/token/logout
Revokes the token given as authentication token (as header). This is equivalent with the ~logout~ end-point, so it logs out the current user. All (refresh) tokens issued for this user will expire and invalidated.
public void com.intershop.beehive.platformrest.resource.auth.TokenResource.tokenLogout()
204 - No Content
401 - Unauthorized
/captcha
Responds with script snippet containing CAPTCHA challenge.
Workflow:
public java.lang.String com.intershop.sellside.rest.common.capi.resource.CaptchaResource.getCaptchaCode()
200 - OK
500 - Internal Server Error response headers will include required fields:
RequiredFields: recaptcha_challenge_field,recaptcha_response_field
/customers/{CustomerKey}/users/{CustomerItemUserKey}/credentials/login
Updates the login of the currently logged in user with a new one.
public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerLoginItemResource.updateLogin(com.intershop.sellside.rest.common.capi.resourceobject.CustomerLoginRO)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item | |
in path | CustomerItemUserKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
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
Updates the password of the currently logged in customer with a new one.
public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item | |
in path | CustomerItemUserKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
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
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.
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
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item | |
in path | CustomerItemUserKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
204 - No Content
400 - Bad Request
401 - Unauthorized
/privatecustomers/{CustomerKey}/credentials/login
Updates the login of the currently logged in user with a new one.
public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerLoginItemResource.updateLogin(com.intershop.sellside.rest.common.capi.resourceobject.CustomerLoginRO)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
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
Updates the password of the currently logged in customer with a new one.
public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
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
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.
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
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
204 - No Content
400 - Bad Request
401 - Unauthorized
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.
The following example shows how to retrieve identity providers for organization Operations:
curl https://<SERVER>/INTERSHOP/rest/WFS/<SITE>/-/identityproviderconfigurations/Operations
/identityproviderconfigurations/{organizationKey}
This operation returns the identity providers that are available for an organization.
public java.util.List com.intershop.beehive.platformrest.resource.identity.IdentityProviderConfigurationResource.getConfigurations(java.lang.String,java.lang.String)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | organizationKey | string | Required | The key of organization | ||
in query | providerType | string | The provider type. If used only matching configurations will be returned. |
200 - OK
404 - Not Found
/identityproviderconfigurations/{organizationKey}/{providerKey}
This operation returns the identity providers that are available for an organization.
public com.intershop.beehive.platformrest.resource.identity.IdentityProviderConfigurationRO com.intershop.beehive.platformrest.resource.identity.IdentityProviderConfigurationResource.getConfiguration(java.lang.String,java.lang.String)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | organizationKey | string | Required | The key of organization | ||
in path | providerKey | string | Required | The key of the configuration |
200 - OK
404 - Not Found
/personalization
public com.intershop.sellside.rest.common.capi.resourceobject.PersonalizationRO com.intershop.sellside.rest.common.capi.resource.PersonalizationResource.getPersonalizationInfo()
200 - OK
401 - Unauthorized
Processes an identity JSON web token. Allows clients to explicitly create users or customers associated with identity providers.
/users/processtoken
public javax.ws.rs.core.Response com.intershop.beehive.platformrest.resource.user.UserTokenResource.processIDToken(com.intershop.beehive.platformrest.resource.user.IDTokenRO)
200 - OK
201 - Created
401 - Unauthorized
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.
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"
}
]
}
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
This operation returns a set of public keys as JSON Web key (JWT) that can be used to verify signatures generated by ICM server.
public net.minidev.json.JSONObject com.intershop.beehive.platformrest.resource.keys.KeyResource.keySet()
200 - OK
/keys/{keyID}
This operation returns the public key as JSON Web key (JWT) with the given key id (claim kid
).
public net.minidev.json.JSONObject com.intershop.beehive.platformrest.resource.keys.KeyResource.key(java.lang.String)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | keyID | string | Required | The key ID |
200 - OK
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.
/customers/{CustomerKey}/users/{CustomerItemUserKey}/credentials/password
Updates the password of the currently logged in customer with a new one.
public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item | |
in path | CustomerItemUserKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
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
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.
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
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item | |
in path | CustomerItemUserKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
204 - No Content
400 - Bad Request
401 - Unauthorized
/privatecustomers/{CustomerKey}/credentials/password
Updates the password of the currently logged in customer with a new one.
public void com.intershop.sellside.rest.common.capi.resource.customer.credentials.CustomerPasswordItemResource.updatePassword(com.intershop.sellside.rest.common.capi.resourceobject.CustomerPasswordRO)
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
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
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.
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
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | CustomerKey | string | ExampleKey | Required | The key or UUID to resolve a single item |
204 - No Content
400 - Bad Request
401 - Unauthorized
/security/password
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.
public void com.intershop.sellside.rest.common.capi.resource.credentials.PasswordResetResource.resetPassword(com.intershop.sellside.rest.common.capi.resourceobject.PasswordResetRO)
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
public com.intershop.sellside.rest.common.capi.resource.credentials.SecurityQuestionListResource$SecurityQuestionsCollectionRO com.intershop.sellside.rest.common.capi.resource.credentials.SecurityQuestionListResource.getSecurityQuestions()
200 - OK
/security/reminder
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".
public void com.intershop.sellside.rest.common.capi.resource.credentials.PasswordReminderResource.sendPassword(com.intershop.sellside.rest.common.capi.resourceobject.PasswordReminderRO)
200 - OK
400 - Bad Request in case when submitted data is missing or invalid
500 - Internal Server Error
pmiller@test.intershop.de
InterShop00
!InterShop00!
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
SecureUserRefRO
object.string
literals. Processing optionsIdentityProviderConfigurationRO
: Properties of an identity provider.uniqueKey
display name
local
JSONWebKey
: A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key.MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4
sig
YPsXB8rdXix5vwsg1F
https://localhost/INTERSHOP/rest/WFS/inSPIRED/-/keys/
goosen@test.intershop.de
Gerhardt
Goosen
Snoopy
mt4KAEsByeIAAAFtwuREkERx
bfd51c73-0e2a-46e1-a3e4-b977a001ae9a
mynewpassword2019
Personalization
HLgg8Yus9qBSR0rCuy4DMI9n0000ys
SecurityQuestion
What is your pet's name?
account.security_question.pet_name.text
int32
int32
int32
SecurityQuestionRO
objects. The list of elementsSecurityQuestionRO
SecurityQuestion
What is your pet's name?
account.security_question.pet_name.text
string
literals. The keys to sort forint64
int64
bearer
| Possible Values: bearer
user
Mr.
12/24/1998
PMerkel