Users resource (Data API 18.7)

Summary

Http Method	Resource	Description
GET	/users/this	Action to get the user password expiration information.
PATCH	/users/this/password	Action to change a user password.
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.
DELETE	/users/{login}	Action to delete a single user.

Get user password expiration information

Action to get the user password expiration information.

Url

GET https://hostname:port/dw/data/v18_7/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/v18_7/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" : "18.7",
   "fault" : 
   {
      "type" : "UserNotAvailableException",
      "message" : "No user was provided with the OAuth token."
   }
}

Change the user password

Action to change a user password.

Url

PATCH https://hostname:port/dw/data/v18_7/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/v18_7/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" : "18.7",
   "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" : "18.7",
   "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" : "18.7",
   "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" : "18.7",
   "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/v18_7/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/v18_7/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]",
    "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" : "18.7",
   "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/v18_7/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.
403	`UserOperationNotAllowedException`	login (String)	If creation or replacement of a user with the given login is not allowed.

Sample

REQUEST:
PUT  /s/-/dw/data/v18_7/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": "18.7",
    "_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" : "18.7",
   "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" : "18.7",
   "fault" :
   {
      "type" : "UnknownLocaleException",
      "message" : "The locale 'aa' is unknown."
   }
}

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" : "18.7",
   "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" : "18.7",
   "fault" :
   {
      "type" : "IdConflictException",
      "message" : "The ID in the request body ('myUser') does not match the ID in the URL ('someUser')."
   }
}

Create User

Action to update a user.

Url

PATCH https://hostname:port/dw/data/v18_7/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.
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/v18_7/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": "18.7",
    "_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" : "18.7",
   "fault" :
   {
      "type" : "UnknownLocaleException",
      "message" : "The locale 'aa' is unknown."
   }
}

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" : "18.7",
   "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" : "18.7",
   "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" : "18.7",
   "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/v18_7/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/v18_7/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" : "18.7",
   "fault" :
   {
      "type" : "UserNotFoundException",
      "message" : "No user with login 'someUser' was 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.