Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > Data API resources 23.2

Users resource (Data API 23.2)

Summary

Http Method	Resource	Description
GET	/users	Action to get all users with no filtering.
GET	/users/this	Action to get the user password expiration information.
PATCH	/users/this/password	Action to change a local user password. This action cannot change the password for a user managed by Account Manager.
GET	/users/{login}	Action to get a user.
PUT	/users/{login}	Action to create or overwrite a user. If a user with the given login already exists, the existing user will be overwritten. If no such login exists, a new user is created.
PATCH	/users/{login}	Action to update a user. Note: The `locked` flag and the user `password` cannot be updated with this resource.
DELETE	/users/{login}	Action to delete a single user.
GET	/users/{login}/access_key/{scope}	Gets a single access key.
PUT	/users/{login}/access_key/{scope}	Creates a single access key (and removes an existing one for the same scope).
DELETE	/users/{login}/access_key/{scope}	Deletes a single access key.
PATCH	/users/{login}/access_key/{scope}	Enables / disables a single access key.

Get Users

Action to get all users with no filtering.

Url

GET https://hostname:port/dw/data/v23_2/users?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

Users

Query Parameters

Parameter	Type	Description
count	Integer	Optional count for retrieving only a subset of the items (default is 25).
select	String	The property selector.
start	Integer	Optional start index for retrieving the items from a given index (default 0).

Sample

REQUEST:
GET /s/-/dw/data/v23_2/users HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118732ed5
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 432
Content-Type: application/json; charset=UTF-8

{
  "_v" : "23.2",
  "_type": "users",
  "count": 2,
  "data": [
    {
      "_type": "user",
      "login": "someUser",
      "link": "https://example.com/s/-/dw/data/v23_2/users/someUser"
    },
    {
      "_type": "user",
      "login": "anotherUser",
      "link": "https://example.com/s/-/dw/data/v23_2/users/anotherUser"
    }
  ],
  "start": 0,
  "total": 2
}

Get user password expiration information

Action to get the user password expiration information.

Url

GET https://hostname:port/dw/data/v23_2/users/this

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

User

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
401	`UserNotAvailableException`		If the user provided by the OAuth token cannot be found.
401	`UserIsLockedException`		If the user profile is currently locked.

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/users/this HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_type": "user",
    "disabled": false,
    "email": "[email protected]",
    "first_name": "Ocapi",
    "last_name": "MultiSite-Full-ReadWriteSitePreferences",
    "locked": false,
    "login": "MultiSite-Full-ReadWriteSitePreferences",
    "password_expiration_date": "2016-01-14T16:48:07Z",
    "password_modification_date":  "2016-04-14T16:48:07Z",
    "preferred_data_locale": "default",
    "preferred_uilocale": "default"
}

# in case of failure:

RESPONSE:
HTTP/1.1 401 UNAUTHORIZED
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "UserNotAvailableException",
      "message" : "No user was provided with the OAuth token."
   }
}

Change a Local User Password

Action to change a local user password. This action cannot change the password for a user managed by Account Manager.

Url

PATCH https://hostname:port/dw/data/v23_2/users/this/password

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Request Document

PasswordChangeRequest

Response Document

User

In case of a failure Fault Document is returned.

Faults

Status	Type	Description
400	`PasswordPolicyViolationException`	If the new password doesn't meet the acceptance crtiteria of a user password.
400	`PasswordNotValidForReuseException`	If the same new password was set recently before.
400	`InvalidPasswordException`	If the provided current user password is invalid.
401	`UserNotAvailableException`	If the user provided by the OAuth token cannot be found.
401	`UserIsLockedException`	If the user profile is currently locked.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.data.users.afterPATCH	afterPatch (login : String , email : String ) : Status The function is called after the users password is updated. Parameters: login - The login of the user. email - The email of the user. Returns: a non-null Status ends the hook execution

Extension Point

Method Detail

dw.ocapi.data.users.afterPATCH

afterPatch (login : String , email : String ) : Status

The function is called after the users password is updated.

Parameters:: login - The login of the user.; email - The email of the user.
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
PATCH /s/-/dw/data/v23_2/users/this/password HTTP/1.1
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Host: example.com
{
   "current_password" : "MyOldPWD1!",
   "password": "MyNewPWD1!"
}
 
# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_type": "user",
    "disabled": false,
    "email": "[email protected]le.com",
    "first_name": "Ocapi",
    "last_name": "MultiSite-Full-ReadWriteSitePreferences",
    "locked": false,
    "login": "MultiSite-Full-ReadWriteSitePreferences",
    "password_expiration_date": "2016-01-14T16:48:07Z",
    "password_modification_date":  "2016-04-14T16:48:07Z",
    "preferred_data_locale": "default",
    "preferred_uilocale": "default"
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 401 UNAUTHORIZED
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "UserNotAvailableException",
      "message" : "No user was provided with the OAuth token."
   }
}

HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "InvalidPasswordException",
      "message" : "The current user password is invalid."
   }
}

HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "PasswordPolicyViolationException",
      "message" : "The provided new password does not meet the acceptance criteria."
   }
}

HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "PasswordNotValidForReuseException",
      "message" : "The password was recently used and is not valid for reuse."
   }
}

Get User

Action to get a user.

Url

GET https://hostname:port/dw/data/v23_2/users/{login}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

User

Path Parameters

Parameter	Type	Description	Constraints
login	String	login of the user	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`UserNotFoundException`	login (String)	If no user with the specified login could be found.

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_type": "user",
    "disabled": false,
    "email": "[email protected]",
    "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
    "first_name": "John",
    "last_name": "Doe",
    "locked": false,
    "login": "someUser",
    "password_expiration_date": "2016-01-14T16:48:07Z",
    "password_modification_date":  "2016-04-14T16:48:07Z",
    "preferred_data_locale": "default",
    "preferred_ui_locale": "en-US",
    "roles": ["FirstRole", "SecondRole"]
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was found."
   }
}

Create User

Action to create or overwrite a user. If a user with the given login already exists, the existing user will be overwritten. If no such login exists, a new user is created.

Url

PUT https://hostname:port/dw/data/v23_2/users/{login}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Request Document

User

Response Document

User

Path Parameters

Parameter	Type	Description	Constraints
login	String	login of the user	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`PasswordPolicyViolationException`		If the password doesn't meet the acceptance crtiteria of a user password.
400	`IdConflictException`	bodyID (String) urlID (String)	If the login in the request URL is different from the login in the request body.
400	`UnknownLocaleException`	locale (String)	If either the Preferred UI Locale or the Preferred Data Locale are unknown.
400	`InvalidCredentialsException`		If password or external id of the user are invalid.
400	`ExternalIdAlreadyExistsException`		If another user with the same external id already exists.
400	`LocalUserCreationException`		If creation of a local Business Manager user is not allowed with the current server settings.
403	`UserOperationNotAllowedException`	login (String)	If creation or replacement of a user with the given login is not allowed.

Sample

REQUEST:
PUT  /s/-/dw/data/v23_2/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 2168cf2b4fbf88ce601bd09c18.7b6aaff14e9360eca75fbbf347818.71574df
Content-Type: application/json; charset=UTF-8
{
    "disabled": false,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "login": "someUser",
    "password": "My$ecurePassword3"
    "preferred_data_locale": "default",
    "preferred_ui_locale": "en-US",
    "roles": ["FirstRole", "SecondRole"]
}

# in case of success:

RESPONSE:
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_v" : "23.2",
    "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.7691ea3d598f2159",
    "_type": "user",
    "disabled": false,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "locked": false,
    "login": "someUser",
    "password_modification_date":  "2016-04-14T16:48:07Z",
    "preferred_data_locale": "default",
    "preferred_ui_locale": "en-US",
    "roles": ["FirstRole", "SecondRole"]
}

# in case of failure:

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "PasswordPolicyViolationException",
      "message" : "The provided new password does not meet the requirements."
   }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UnknownLocaleException",
      "message" : "The locale 'aa' is unknown."
   }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "InvalidCredentialsException",
      "message" : "Password and external id must not be provided at the same time."
   }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "ExternalIdNotAllowedException",
      "message" : "Attribute 'external_id' is not allowed with the current server settings."
   }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "ExternalIdAlreadyExistsException",
      "message" : "Another user with the same external id already exists."
   }
}

RESPONSE:
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserOperationNotAllowedException",
      "message" : "The operation is not allowed for the user with login 'someUser'."
   }
}

RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "IdConflictException",
      "message" : "The ID in the request body ('myUser') does not match the ID in the URL ('someUser')."
   }
}

Update User

Action to update a user.

Note: The locked flag and the user password cannot be updated with this resource.

Url

PATCH https://hostname:port/dw/data/v23_2/users/{login}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Request Document

User

Response Document

User

Path Parameters

Parameter	Type	Description	Constraints
login	String	login of the user	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`IdConflictException`	bodyID (String) urlID (String)	If the login in the request URL is different from the login in the request body.
400	`UnknownLocaleException`	locale (String)	If either the Preferred UI Locale or the Preferred Data Locale are unknown.
400	`ExternalIdAlreadyExistsException`		If another user with the same external id already exists.
400	`ExternalIdNullException`		If the external id is explicitly set to null for an externally managed user
403	`UserOperationNotAllowedException`	login (String)	If creation or replacement of a user with the given login is not allowed.
404	`UserNotFoundException`	login (String)	If no user with the specified login could be found.

Sample

REQUEST:
PATCH  /s/-/dw/data/v23_2/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 2168cf2b4fbf88ce601bd09c18.7b6aaff14e9360eca75fbbf347818.71574df
Content-Type: application/json; charset=UTF-8
{
    "disabled": false,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "login": "someUser",
    "preferred_data_locale": "default",
    "preferred_ui_locale": "en-US",
    "roles": ["ThirdRole"]
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_v" : "23.2",
    "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.7691ea3d598f2159",
    "_type": "user",
    "disabled": false,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "locked": false,
    "login": "someUser",
    "password_modification_date":  "2016-04-14T16:48:07Z",
    "preferred_data_locale": "default",
    "preferred_ui_locale": "en-US",
    "roles": ["ThirdRole"]
}

# in case of failure:

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UnknownLocaleException",
      "message" : "The locale 'aa' is unknown."
   }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "ExternalIdNotAllowedException",
      "message" : "Attribute 'external_id' is not allowed with the current server settings."
   }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "ExternalIdAlreadyExistsException",
      "message" : "Another user with the same external id already exists."
   }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "ExternalIdNullException",
      "message" : "The external id of a user must not be removed during update."
   }
}

RESPONSE:
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserOperationNotAllowedException",
      "message" : "The operation is not allowed for the user with login 'someUser'."
   }
}

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was found."
   }
}

RESPONSE:
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "IdConflictException",
      "message" : "The ID in the request body ('myUser') does not match the ID in the URL ('someUser')."
   }
}

Delete User

Action to delete a single user.

Url

DELETE https://hostname:port/dw/data/v23_2/users/{login}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Path Parameters

Parameter	Type	Description	Constraints
login	String	login of the user	minLength=1

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
404	`UserNotFoundException`	login (String)	If no user with the specified login could be found.

Sample

REQUEST:
DELETE  /s/-/dw/data/v23_2/users/someUser HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was found."
   }
}

Get access key

Gets a single access key.

Url

GET https://hostname:port/dw/data/v23_2/users/{login}/access_key/{scope}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token. A valid user is required.

Response Document

AccessKeyDetails

Path Parameters

Parameter	Type	Description	Constraints
login	String	The login of the user.	mandatory=true, minLength=1, nullable=false
scope	String	The scope of the access key.	mandatory=true, nullable=false, strings=["WEBDAV_AND_STUDIO", "AGENT_USER_AND_OCAPI", "STOREFRONT"]

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
403	`UserAccessForbiddenException`	method (String) path (String)	When the user executing the request is missing the required functional permission 'Manage_Users_Access_Keys'.
403	`UserNotExternallyManagedException`	login (String)	When the specified user is not externally managed.
404	`AuthenticationScopeNotFoundException`	scope (String)	If the access scope does not exist.
404	`UserNotFoundException`	login (String)	If no user was found for the login.
404	`AccessKeyNotFoundException`	login (String) scope (String)	If the access key does not exist.

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/users/someUser/access_key/STOREFRONT HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_type": "access_key_details",
    "enabled": true,
    "expiration_date": "2023-04-05T10:19:59.408Z"
}

# in case of not existing user:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was found."
   }
}

# in case of unknown scope
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "StringConstraintViolationException",
      "message" : "The 'scope' string length constraint was violated. The expected length is '(0..2147483647)'."
   }
}

# in case of missing functonal permissions

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v23_2/users/someUser/access_key/STOREFRONT' isn't allowed for the current user."
   }
}

# in case of specifying a local user

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotExternallyManagedException",
      "message" : "The user with login 'someUser' isn't externally managed."
   }
}

# in case of missing access key

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "AccessKeyNotFoundException",
      "message" : "No access key for login 'someUser' and authentication scope 'STOREFRONT' could be found."
   }
}

Creates access key

Creates a single access key (and removes an existing one for the same scope).

Url

PUT https://hostname:port/dw/data/v23_2/users/{login}/access_key/{scope}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token. A valid user is required.

Request Document

The call does not accept a request body.

Response Document

AccessKeyDetails

Path Parameters

Parameter	Type	Description	Constraints
login	String	The login of the user.	mandatory=true, minLength=1, nullable=false
scope	String	The scope of the access key.	mandatory=true, nullable=false, strings=["WEBDAV_AND_STUDIO", "AGENT_USER_AND_OCAPI", "STOREFRONT"]

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
400	`AccessKeyIsExpiredException`	login (String) scope (String)	If the acces key is already expired.
403	`UserAccessForbiddenException`	method (String) path (String)	When the user executing the request is missing the required functional permission 'Manage_Users_Access_Keys'.
403	`UserNotExternallyManagedException`	login (String)	When the specified user is not externally managed.
404	`AuthenticationScopeNotFoundException`	scope (String)	If the access scope does not exist.
404	`UserNotFoundException`	login (String)	If no user was found for the login.

Sample

REQUEST:
PUT  /s/-/dw/data/v23_2/users/someUser/access_key/STOREFRONT HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_v": "23.2",
    "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a41823691ea3d598f2159",
    "_type": "user",
    "disabled": false,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "locked": false,
    "login": "someUser",
    "password_modification_date":  "2016-04-14T16:48:07Z",
    "preferred_data_locale": "default",
    "preferred_ui_locale": "en-US",
    "roles": ["FirstRole", "SecondRole"]
}

# in case of not existing user:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was found."
   }
}

# in case of unknown scope
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "StringConstraintViolationException",
      "message" : "The 'scope' string length constraint was violated. The expected length is '(0..2147483647)'."
   }
}

# in case of missing functonal permissions

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v23_2/users/someUser/access_key/STOREFRONT' isn't allowed for the current user."
   }
}

# in case of specifying a local user

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotExternallyManagedException",
      "message" : "The user with login 'someUser' isn't externally managed."
   }
}

# in case of missing access key

Delete access key

Deletes a single access key.

Url

DELETE https://hostname:port/dw/data/v23_2/users/{login}/access_key/{scope}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token. A valid user is required.

Path Parameters

Parameter	Type	Description	Constraints
login	String	The login of the user.	mandatory=true, minLength=1, nullable=false
scope	String	The scope of the access key.	mandatory=true, nullable=false, strings=["WEBDAV_AND_STUDIO", "AGENT_USER_AND_OCAPI", "STOREFRONT"]

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
403	`UserAccessForbiddenException`	method (String) path (String)	When the user executing the request is missing the required functional permission 'Manage_Users_Access_Keys'.
403	`UserNotExternallyManagedException`	login (String)	When the specified user is not externally managed.
404	`AuthenticationScopeNotFoundException`	scope (String)	If the access scope does not exist.
404	`UserNotFoundException`	login (String)	If no user was found for the login.
404	`AccessKeyNotFoundException`	login (String) scope (String)	If the access key does not exist.

Sample

REQUEST:
DELETE  /s/-/dw/data/v23_2/users/someUser/access_key/STOREFRONT HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of not existing user:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was found."
   }
}

# in case of unknown scope
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "StringConstraintViolationException",
      "message" : "The 'scope' string length constraint was violated. The expected length is '(0..2147483647)'."
   }
}

# in case of missing functonal permissions

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v23_2/users/someUser/access_key/STOREFRONT' isn't allowed for the current user."
   }
}

# in case of specifying a local user

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotExternallyManagedException",
      "message" : "The user with login 'someUser' isn't externally managed."
   }
}

# in case of missing access key

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "AccessKeyNotFoundException",
      "message" : "No access key for login 'someUser' and authentication scope 'STOREFRONT' could be found."
   }
}

Enable / disable access key

Enables / disables a single access key.

Url

PATCH https://hostname:port/dw/data/v23_2/users/{login}/access_key/{scope}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token. A valid user is required.

Request Document

AccessKeyUpdateRequest

Response Document

AccessKeyDetails

Path Parameters

Parameter	Type	Description	Constraints
login	String	The login of the user.	mandatory=true, minLength=1, nullable=false
scope	String	The scope of the access key.	mandatory=true, nullable=false, strings=["WEBDAV_AND_STUDIO", "AGENT_USER_AND_OCAPI", "STOREFRONT"]

In case of a failure Fault Document is returned.

Faults

Status	Type	Arguments	Description
403	`UserAccessForbiddenException`	method (String) path (String)	When the user executing the request is missing the required functional permission 'Manage_Users_Access_Keys'.
403	`UserNotExternallyManagedException`	login (String)	When the specified user is not externally managed.
404	`AuthenticationScopeNotFoundException`	scope (String)	If the access scope does not exist.
404	`UserNotFoundException`	login (String)	If no user was found for the login.
404	`AccessKeyNotFoundException`	login (String) scope (String)	If the access key does not exist.

Sample

REQUEST:
PATCH  /s/-/dw/data/v23_2/users/someUser/access_key/STOREFRONT HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 2168cf2b4fbf88ce601bd09c18b6b6aaff14e9360eca75fbbf347818a31574df
Content-Type: application/json; charset=UTF-8
{
    "enabled": false
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_type": "access_key_details",
    "enabled": false,
    "expiration_date": "2023-04-05T10:19:59.408Z"
}

# in case of not existing user:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was found."
   }
}

# in case of unknown scope
RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "StringConstraintViolationException",
      "message" : "The 'scope' string length constraint was violated. The expected length is '(0..2147483647)'."
   }
}

# in case of missing functonal permissions

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v23_2/users/someUser/access_key/STOREFRONT' isn't allowed for the current user."
   }
}

# in case of specifying a local user

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "UserNotExternallyManagedException",
      "message" : "The user with login 'someUser' isn't externally managed."
   }
}

# in case of missing access key

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "type" : "AccessKeyNotFoundException",
      "message" : "No access key for login 'someUser' and authentication scope 'STOREFRONT' could be found."
   }
}

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.