IBM Watson Content Hub API

Live

IBM Watson Content Hub API

+ Day(s) remaining in the trial

Introduction

IBM Watson Content Hub is a cloud content management system with integrated asset classification features from IBM Watson. Developers can use APIs to create and manage content, and to integrate content into their mobile applications, web apps, or any other channel where content is required. The product also provides a graphical user interface for business users to create and manage content. The following APIs are now available for Watson Content Hub: - Authoring services APIs, which require authentication and are not optimized for retrieval by applications in production. - Delivery services APIs, which can be accessed anonymously and are optimized for caching and performance. The two APIs are similar and you can switch between the authoring and delivery services by changing the URL path in the code. For example, change the path from authoring to resources in the following authoring resource URL https://{DomainName}/{path}/authoring/v1/resources/{resource-id} to switch to the delivery resource service URL https://{DomainName}/{path}/delivery/v1/resources/{resource-id}. Note: Since the Authoring services require authentication you can switch from the delivery resource URL only after the log in call.

Getting started

Authentication

Most of the IBM Watson Content Hub REST API services require authentication before you can access them. The following instructions describe how to get authentication and then call the authenticated APIs.

To make authenticated IBM Watson Content Hub REST API calls, you need the following information:

  1. The API URL for your tenant, for example https://my12.digitalexperience.ibm.com/api/12345678-9abc-def0-1234-56789abcdef0.
  2. A cookie that contains the authentication token.

Note: Although the samples on the right hand side of the IBM Watson Content Hub API documentation mention setting the headers X-IBM-Client-Id and X-IBM-Client-Secret they are currently not needed. For more information, see the API Keys section.

Obtaining the API URL for your tenant to use the IBM Watson Content Hub API

You can get the API URL in one of the following ways:

  1. From the IBM Watson Content Hub user interface

    Open the User menu by clicking the drop down arrow near the user name and then click Hub information. A pop-up window displays the items Content hub ID and Domain name.

    In the IBM Watson Content Hub API, besides the place-holder {DomainName} the place-holder {path} is used which is constructed as {path} = api/{Content hub ID}. Therefore, the API URL to access the IBM Watson Content Hub API is constructed as follows: {API URL} = https://{DomainName}/{path}.

  2. By calling the IBM Watson Content Hub login service

    The following cURL example shows how to retrieve the Domain name and the Content hub ID by calling the login service.

    curl -v -u blueidUser@domain.com:password https://my.digitalexperience.ibm.com/api/login/v1/basicauth

    The call returns the header x-ibm-dx-tenant-base-url, which contains the API URL.

For example, you would get {DomainName} = my12.digitalexperience.ibm.com and {path} = api/12345678-9abc-def0-1234-56789abcdef0. In the following API description, replace the {DomainName} and {path} place-holders with your specific data.

Obtaining the authentication token with HTTP Basic authentication

Log in with the API URL and retrieve the authentication token. For example, login and retrieve the authentication token with the following cURL command:

curl -v -c cookie.txt -u blueidUser@domain.com:password https://{DomainName}/{path}/login/v1/basicauth

This command stores the authentication token in the file cookie.txt.

Using the obtained information to call an API

For example, the request https://{DomainName}/{path}/authoring/v1/assets converts to the following command:

curl -b cookie.txt https://my12.digitalexperience.ibm.com/api/12345678-9abc-def0-1234-56789abcdef0/authoring/v1/assets

You can find a link in the resources section that provides more examples of authenticated calls to IBM Watson Content Hub.

User Roles

Each API service operation has a set of user roles that are allowed for the operation. You can call only the service operations that are allowed for the specific role a user has.

The roles are organized in a hierarchy, that means each role in the list below has more rights than the roles following this role. For example, the Editor role has more rights than the Viewer and Anonymous role but less rights than Administrator and Manager.

The roles are

  • Administrator - can access all functionality including tenant administration tasks such as adding/removing users.
  • Manager - can create and manage content model, content, and assets.
  • Editor - can create and manage content and assets.
  • Viewer - can retrieve content and assets via the authoring APIs, but does not have access to the authoring UI.
  • Anonymous - cannot access any authoring functionality.

HTTPS Settings

IBM Watson Content Hub is configured for HTTPS usage. All HTTP requests are redirected to HTTPS. The enabled protocol is TLS 1.2 (strict). Ensure that you connect to IBM Watson Content Hub only with clients that support TLS 1.2. Clients that do not support the protocol cannot establish connection.

Note: Some clients that support TLS 1.2 have older protocols that are enabled by default, in this case change the configuration of your client to include TLS 1.2.

CORS support for API access from client-side JS

Cross-Origin Resource Sharing (CORS) can be used to enable secure cross-domain data transfers in client-side JavaScript. If you are calling IBM Watson Content Hub services from client-side JavaScript that is hosted on a different domain, you need to enable CORS for that domain. You must add only domains that require access to the content and assets stored in your content hub, such as your web servers or your development environment.

The domain format must be protocol://server:port. Here, the protocol is either http or https, the server is either your server name or its IP address, and the port is the port number of your server, for example, http://my.domain.org:80. You can also use the * wildcard to enable CORS for any domain.

To control the CORS enablement for IBM Watson Content Hub, from the menu bar in the IBM Watson Content Hub user interface, open Hub Setup and select General Settings and then open the Security tab.

API Keys

The following two API key values are not currently used by IBM Watson Content Hub, but in the future they will be required headers in API calls. The headers are X-IBM-Client-Id and X-IBM-Client-Secret.

The API keys can be obtained by the primary subscriber to IBM Watson Content Hub. The subscriber must open the API Explorer, the API keys are listed on the My APIs page.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.


Manage your keys
 

Global Parameters

This section contains global variables, which apply to all of the endpoint definitions of this API. You can use this section to set these variables once, and have the values pre-filled for every endpoint in the Documentation section. The values set can be used with the built-in testing. You can always override the value in the endpoint definition of the Documentation section.
Global variables

The tenant-specific Domain name to connect to the API. For more information, see the Getting Started section.


The tenant-specific, constant path part of REST API URLs. For more information, see the Getting Started section.

Documentation

IBM Watson Content Hub API:

Administering user profiles

Add a new user.
Adds a new user and returns the user object.
User roles: admin

POST   /user-profile/v1/users

														https://{DomainName}/{path}/user-profile/v1/users
													
Keys
Global variables

DomainName

BASEURL , required

The tenant-specific Domain name to connect to the API. For more information, see the Getting Started section.

path

BASEURL , required

The tenant-specific, constant path part of REST API URLs. For more information, see the Getting Started section.

Request code
								
HttpResponse<String> response = Unirest.post("https://{DomainName}/{path}/user-profile/v1/users") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"displayName\":\"string\",\"externalId\":\"string\",\"firstName\":\"string\",\"lastName\":\"string\",\"roles\":[null]}") .asString();
Request model

externalId

STRING , required

The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address.

firstName

STRING , optional

The first name of the user

lastName

STRING , optional

The last name of the user

displayName

STRING , optional

The name of the user that can be displayed in the UI

roles

ARRAY , required

The roles of the user that will be used for access control

ARRAY , optional

The roles of the user that will be used for access control

Request example
{
  "externalId": string,
  "firstName": string,
  "lastName": string,
  "displayName": string,
  "roles": [{
    "": []
  }]
}
Response model

201

User was created successfully.

Body

id

STRING , required

The unique internal identifier of the user

externalId

STRING , required

The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address.

firstName

STRING , optional

The first name of the user

lastName

STRING , optional

The last name of the user

displayName

STRING , optional

The name of the user that can be displayed in the UI

roles

ARRAY , optional

The roles of the user that will be used for access control (empty for the anonymous user)

links

object , optional

lastLogin

STRING , optional

Date when this user logged in for the last time before current session

created

STRING , optional

Date when this item was created

creator

object , optional

lastModified

STRING , optional

Date when this item was modified for the last time

lastModifier

object , optional

self

object , optional

href

STRING , required

methods

ARRAY , optional

name

object , optional

id

STRING , required

id

STRING , required

400

Response indicating a client error.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code defined by the User Profile service.

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

409

A user with same externalID does already exist.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code defined by the User Profile service.

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

Response example

201

User was created successfully.

								{
  "id" : string,
  "externalId" : string,
  "firstName" : string,
  "lastName" : string,
  "displayName" : string,
  "roles" : [string],
  "links" : {
    "self" : {
    "href" : string,
    "methods" : [string],
    "name" : object
  }
  },
  "lastLogin" : string,
  "created" : string,
  "creator" : {
    "id" : string
  },
  "lastModified" : string,
  "lastModifier" : {
    "id" : string
  }
}
							

400

Response indicating a client error.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

409

A user with same externalID does already exist.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							
Delete an existing user.
Deletes an existing user.
User roles: admin

DELETE   /user-profile/v1/users/{id}

														https://{DomainName}/{path}/user-profile/v1/users/{id}
													
Keys
Global variables

DomainName

BASEURL , required

The tenant-specific Domain name to connect to the API. For more information, see the Getting Started section.

path

BASEURL , required

The tenant-specific, constant path part of REST API URLs. For more information, see the Getting Started section.

Path and Query parameters

id

URL , required

The unique internal identifier of the entity that should be processed

Request code
								
HttpResponse<String> response = Unirest.delete("https://{DomainName}/{path}/user-profile/v1/users/{id}") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

204

User was deleted successfully.

400

Response indicating a client error.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code defined by the User Profile service.

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

404

The given ID cannot be resolved.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

Response example

204

User was deleted successfully.

400

Response indicating a client error.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

404

The given ID cannot be resolved.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							
Find all users.
Returns an array containing all users matching the query.
User roles: admin

GET   /user-profile/v1/users

														https://{DomainName}/{path}/user-profile/v1/users
													
Keys
Global variables

DomainName

BASEURL , required

The tenant-specific Domain name to connect to the API. For more information, see the Getting Started section.

path

BASEURL , required

The tenant-specific, constant path part of REST API URLs. For more information, see the Getting Started section.

Path and Query parameters

external-id

STRING , optional

The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address.

include

ARRAY , optional

Include additional information sections

limit

INTEGER , optional

The maximum number of items to be included in the response

offset

INTEGER , optional

The index of the first item to be included in the response

Request code
								
HttpResponse<String> response = Unirest.get("https://{DomainName}/{path}/user-profile/v1/users?external-id=string&offset=0&limit=10&include=undefined") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Returns a (sub-)list of all available users. At most [limit] items are returned.

Body

limit

INTEGER , required

Maximum number of items in the current sublist

links

object , optional

offset

INTEGER , required

Number of skipped items, the first item in this sublist list will be (offset)

first

object , optional

next

object , optional

prev

object , optional

self

object , optional

href

STRING , required

href

STRING , required

href

STRING , required

href

STRING , required

methods

ARRAY , optional

name

object , optional

400

Response indicating a client error.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code defined by the User Profile service.

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

Response example

200

Returns a (sub-)list of all available users. At most [limit] items are returned.

								{
  "limit" : integer,
  "links" : {
    "first" : {
    "href" : string
  },
    "next" : {
    "href" : string
  },
    "prev" : {
    "href" : string
  },
    "self" : {
    "href" : string,
    "methods" : [string],
    "name" : object
  }
  },
  "offset" : integer
}
							

400

Response indicating a client error.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							
Find the current user
Returns the current user
User roles: admin, manager, editor, viewer, anonymous

GET   /user-profile/v1/users/currentuser

														https://{DomainName}/{path}/user-profile/v1/users/currentuser
													
Keys
Global variables

DomainName

BASEURL , required

The tenant-specific Domain name to connect to the API. For more information, see the Getting Started section.

path

BASEURL , required

The tenant-specific, constant path part of REST API URLs. For more information, see the Getting Started section.

Request code
								
HttpResponse<String> response = Unirest.get("https://{DomainName}/{path}/user-profile/v1/users/currentuser") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Returns the current user

Body

id

STRING , required

The unique internal identifier of the user

externalId

STRING , required

The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address.

firstName

STRING , optional

The first name of the user

lastName

STRING , optional

The last name of the user

displayName

STRING , optional

The name of the user that can be displayed in the UI

roles

ARRAY , optional

The roles of the user that will be used for access control (empty for the anonymous user)

links

object , optional

lastLogin

STRING , optional

Date when this user logged in for the last time before current session

created

STRING , optional

Date when this item was created

creator

object , optional

lastModified

STRING , optional

Date when this item was modified for the last time

lastModifier

object , optional

self

object , optional

href

STRING , required

methods

ARRAY , optional

name

object , optional

id

STRING , required

id

STRING , required

400

Response indicating a client error

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code defined by the User Profile service.

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

Response example

200

Returns the current user

								{
  "id" : string,
  "externalId" : string,
  "firstName" : string,
  "lastName" : string,
  "displayName" : string,
  "roles" : [string],
  "links" : {
    "self" : {
    "href" : string,
    "methods" : [string],
    "name" : object
  }
  },
  "lastLogin" : string,
  "created" : string,
  "creator" : {
    "id" : string
  },
  "lastModified" : string,
  "lastModifier" : {
    "id" : string
  }
}
							

400

Response indicating a client error

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							
Find user by ID.
Returns a single user.
User roles: admin

GET   /user-profile/v1/users/{id}

														https://{DomainName}/{path}/user-profile/v1/users/{id}
													
Keys
Global variables

DomainName

BASEURL , required

The tenant-specific Domain name to connect to the API. For more information, see the Getting Started section.

path

BASEURL , required

The tenant-specific, constant path part of REST API URLs. For more information, see the Getting Started section.

Path and Query parameters

id

URL , required

The unique internal identifier of the entity that should be processed or the special value currentuser that uses the ID provided in the userID header.

Request code
								
HttpResponse<String> response = Unirest.get("https://{DomainName}/{path}/user-profile/v1/users/{id_string}") .header("accept", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .asString();
Response model

200

Returns the user object for the given user.

Body

id

STRING , required

The unique internal identifier of the user

externalId

STRING , required

The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address.

firstName

STRING , optional

The first name of the user

lastName

STRING , optional

The last name of the user

displayName

STRING , optional

The name of the user that can be displayed in the UI

roles

ARRAY , optional

The roles of the user that will be used for access control (empty for the anonymous user)

links

object , optional

lastLogin

STRING , optional

Date when this user logged in for the last time before current session

created

STRING , optional

Date when this item was created

creator

object , optional

lastModified

STRING , optional

Date when this item was modified for the last time

lastModifier

object , optional

self

object , optional

href

STRING , required

methods

ARRAY , optional

name

object , optional

id

STRING , required

id

STRING , required

400

Response indicating a client error.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code defined by the User Profile service.

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

404

The given ID cannot be resolved.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

Response example

200

Returns the user object for the given user.

								{
  "id" : string,
  "externalId" : string,
  "firstName" : string,
  "lastName" : string,
  "displayName" : string,
  "roles" : [string],
  "links" : {
    "self" : {
    "href" : string,
    "methods" : [string],
    "name" : object
  }
  },
  "lastLogin" : string,
  "created" : string,
  "creator" : {
    "id" : string
  },
  "lastModified" : string,
  "lastModifier" : {
    "id" : string
  }
}
							

400

Response indicating a client error.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

404

The given ID cannot be resolved.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							
Update an existing user.
Updates an existing user and returns the updated user object.
User roles: admin

PUT   /user-profile/v1/users/{id}

														https://{DomainName}/{path}/user-profile/v1/users/{id}
													
Keys
Global variables

DomainName

BASEURL , required

The tenant-specific Domain name to connect to the API. For more information, see the Getting Started section.

path

BASEURL , required

The tenant-specific, constant path part of REST API URLs. For more information, see the Getting Started section.

Path and Query parameters

id

URL , required

The unique internal identifier of the entity that should be processed

Request code
								
HttpResponse<String> response = Unirest.put("https://{DomainName}/{path}/user-profile/v1/users/{id}") .header("accept", "application/json") .header("content-type", "application/json") .header("x-ibm-client-id", "REPLACE_KEY_VALUE") .header("x-ibm-client-secret", "REPLACE_KEY_VALUE") .body("{\"created\":\"string\",\"creator\":{\"description\":\"URI pointing to the User who has created the item\",\"properties\":{\"id\":\"string\"},\"required\":[\"id\"],\"type\":\"object\"},\"displayName\":\"string\",\"externalId\":\"string\",\"firstName\":\"string\",\"id\":\"string\",\"lastModified\":\"string\",\"lastModifier\":{\"description\":\"URI pointing to the User who has modified the item\",\"properties\":{\"id\":\"string\"},\"required\":[\"id\"],\"type\":\"object\"},\"lastName\":\"string\",\"links\":{\"type\":\"object\"},\"roles\":[null]}") .asString();
Request model

id

STRING , optional

The unique internal identifier of the user

externalId

STRING , optional

The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address.

firstName

STRING , optional

The first name of the user

lastName

STRING , optional

The last name of the user

displayName

STRING , optional

The name of the user that can be displayed in the UI

roles

ARRAY , required

The roles of the user that will be used for access control

links

OBJECT , optional

created

STRING , optional

Date when this item was created

creator

OBJECT , optional

URI pointing to the User who has created the item

lastModified

STRING , optional

Date when this item was modified for the last time

lastModifier

OBJECT , optional

URI pointing to the User who has modified the item

ARRAY , optional

The roles of the user that will be used for access control

id

STRING , required

id

STRING , required

Request example
{
  "id": string,
  "externalId": string,
  "firstName": string,
  "lastName": string,
  "displayName": string,
  "roles": [{
    "": []
  }],
  "links": object,
  "created": string,
  "creator": {
    "id": string
  },
  "lastModified": string,
  "lastModifier": {
    "id": string
  }
}
Response model

200

The user was updated successfully.

Body

id

STRING , required

The unique internal identifier of the user

externalId

STRING , required

The unique external identifier of the user (e.g. BlueID). Although, this field can store email addresses, other types of unique identifiers may be stored too. Do not use this field as a replacement for the user attribute email address.

firstName

STRING , optional

The first name of the user

lastName

STRING , optional

The last name of the user

displayName

STRING , optional

The name of the user that can be displayed in the UI

roles

ARRAY , optional

The roles of the user that will be used for access control (empty for the anonymous user)

links

object , optional

lastLogin

STRING , optional

Date when this user logged in for the last time before current session

created

STRING , optional

Date when this item was created

creator

object , optional

lastModified

STRING , optional

Date when this item was modified for the last time

lastModifier

object , optional

self

object , optional

href

STRING , required

methods

ARRAY , optional

name

object , optional

id

STRING , required

id

STRING , required

400

Response indicating a client error.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code defined by the User Profile service.

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

404

The given ID cannot be resolved.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

Body

errors

ARRAY , optional

requestId

STRING , required

The ID of the failing request.

service

STRING , optional

The name of the service serving the error message.

code

INTEGER , required

An error code

message

STRING , required

A message describing what went wrong.

description

STRING , optional

Further explanation of the error condition and potential next steps to resolve the problem.

more_info

STRING , optional

A URL pointing to a web site that provides more information on the given error condition.

level

STRING , optional

The severity level of the message. Default is error.

parameters

object , optional

cause

object , optional

locale

STRING , optional

This property represents the locale of the text contained in properties 'message', and 'description'. This property is mandatory if message and description contain translated text.

Response example

200

The user was updated successfully.

								{
  "id" : string,
  "externalId" : string,
  "firstName" : string,
  "lastName" : string,
  "displayName" : string,
  "roles" : [string],
  "links" : {
    "self" : {
    "href" : string,
    "methods" : [string],
    "name" : object
  }
  },
  "lastLogin" : string,
  "created" : string,
  "creator" : {
    "id" : string
  },
  "lastModified" : string,
  "lastModifier" : {
    "id" : string
  }
}
							

400

Response indicating a client error.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

404

The given ID cannot be resolved.

429

Too Many Requests, the server has reached a limit, the request must be sent again at a later time.

								{
  "errors" : [{
    "code" : integer,
    "message" : string,
    "description" : string,
    "more_info" : string,
    "level" : [ERROR, WARNING],
    "parameters" : object,
    "cause" : object,
    "locale" : string
  }],
  "requestId" : string,
  "service" : string
}
							

Loading content...