Users resource (Data API 22.6)

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/v22_6/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 Constraints
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/v22_6/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" : "22.6",
  "_type": "users",
  "count": 2,
  "data": [
    {
      "_type": "user",
      "login": "someUser",
      "link": "https://example.com/s/-/dw/data/v22_6/users/someUser"
    },
    {
      "_type": "user",
      "login": "anotherUser",
      "link": "https://example.com/s/-/dw/data/v22_6/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/v22_6/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/v22_6/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" : "22.6",
   "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/v22_6/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 Arguments 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

Sample

REQUEST:
PATCH /s/-/dw/data/v22_6/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]",
    "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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/v22_6/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/v22_6/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" : "22.6",
   "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/v22_6/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/v22_6/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" : "22.6",
    "_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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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/v22_6/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/v22_6/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" : "22.6",
    "_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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "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/v22_6/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/v22_6/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" : "22.6",
   "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/v22_6/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/v22_6/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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v22_6/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" : "22.6",
   "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" : "22.6",
   "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/v22_6/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/v22_6/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": "22.6",
    "_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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v22_6/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" : "22.6",
   "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/v22_6/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/v22_6/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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v22_6/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" : "22.6",
   "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" : "22.6",
   "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/v22_6/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/v22_6/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" : "22.6",
   "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" : "22.6",
   "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" : "22.6",
   "fault" :
   {
      "type" : "UserAccessForbiddenException",
      "message" : "Access to resource 'DELETE /data/v22_6/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" : "22.6",
   "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" : "22.6",
   "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.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.