{ "schemes": [ "https" ], "swagger": "2.0", "security": [ { "basic_auth": [ ] } ], "basePath": "/instance/services", "paths": { "/csrf_token": { "post": { "summary": "Obtain a CSRF token.", "description": "Obtain a CSRF token.", "operationId": "createCsrfToken", "tags": [ "CSRF" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "csrf_request", "in": "body", "description": "A mandatory parameter for specifying the lifetime of the retrieved CSRF token.", "required": true, "schema": { "$ref": "#/definitions/csrf_request" } } ], "responses": { "201": { "description": "The request was processed successfully and returned a new CSRF token", "schema": { "$ref": "#/definitions/csrf_token" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/password_policy": { "get": { "summary": "Retrieve password policy rules for the current user.", "description": "Retrieve password policy rules for the current user.", "operationId": "getPasswordPolicy", "tags": [ "Current User" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The request was processed successfully and returned the password policy.", "schema": { "$ref": "#/definitions/password_policy" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/user_record": { "get": { "summary": "Get the record of the current user from the subscription.", "description": "Get the record of the current user from the subscription.", "operationId": "getUserRecord", "tags": [ "Current User" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "Cross-site request forgery (CSRF) prevention token for REST APIs.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The request was processed successfully and returned the user data.", "schema": { "$ref": "#/definitions/user_record" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/user_session_terminate": { "post": { "summary": "Terminate the session used by the calling user for this call.", "description": "Terminate the session used by the calling user for this call.", "operationId": "terminateUserSession", "tags": [ "Current User" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "Cross-site request forgery (CSRF) prevention token for REST APIs. The header has to be provided, an arbitrary value is permitted.", "required": true, "type": "string" } ], "responses": { "204": { "description": "The session was successfully terminated." }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/user_trial_mode": { "put": { "summary": "Update the trial mode for current user.", "description": "Update the trial mode for the current user, i. e. enable or disable expert mode.", "operationId": "setTrialMode", "tags": [ "Current User" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "Cross-site request forgery (CSRF) prevention token for REST APIs.", "required": true, "type": "string" }, { "name": "user_trial_mode", "in": "body", "description": "The expert settings for the current user.", "required": true, "schema": { "$ref": "#/definitions/user_trial_mode" } } ], "responses": { "204": { "description": "The request was processed successfully." }, "400": { "description": "The request contains invalid parameters.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The requested user or group cannot be found.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/user_trial_extension": { "post": { "summary": "Extend the trial for the current user.", "description": "Extend the trial period for the current user.", "operationId": "requestTrialExtension", "tags": [ "Current User" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "Cross-site request forgery (CSRF) prevention token for REST APIs.", "required": true, "type": "string" } ], "responses": { "201": { "description": "The request was processed successfully.", "schema": { "$ref": "#/definitions/trial" } }, "400": { "description": "The request contains invalid parameters.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The trial can not be extended, for example, because the user has already extended their trial once.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/bulk/users": { "post": { "summary": "Invite a set of new users to the subscription.", "description": "Invites a set of new users to the subscription. Only account administrators are authorized to perform this call.", "operationId": "inviteUserBulk", "tags": [ "User Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "users", "in": "body", "description": "The users you want to invite to the subscription.", "required": true, "schema": { "$ref": "#/definitions/users" } }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'details', 'groups'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "details", "groups" ] }, "collectionFormat": "csv" }, { "name": "activate_automatically", "in": "query", "description": "Use for SAML authentication only. Parameter to activate users automatically on the subscription. Set the value to 'true' and use it with the 'skip_email' parameter set to 'true'.", "required": false, "default": false, "type": "boolean" }, { "name": "skip_email", "in": "query", "description": "Skip sending the invitation email that contains the activation token.", "required": false, "default": false, "type": "boolean" } ], "responses": { "200": { "description": "The request was processed successfully. The response contains information about which user was successfully invited and error details if some of the specified users could not be invited.", "schema": { "$ref": "#/definitions/user_bulk_result" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/users": { "get": { "summary": "Retrieve a list of users for this subscription.", "description": "Gets a list of users for this subscription. Only account administrators are authorized to perform this call.", "operationId": "getUsersList", "tags": [ "User Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "search_term", "in": "query", "description": "An optional parameter to search for a user. If set, the call returns users where the search term is contained in the user ID, email, given name or family name. The parameter does not support wildcards and it is not case sensitive.", "required": false, "type": "string" }, { "name": "offset", "in": "query", "description": "The number of entries to skip in the query result set before returning an entry. For example, if the offset is 2, entries are returned starting from the third entry in the result set.", "required": false, "type": "integer", "default": 0, "minimum": 0 }, { "name": "size", "in": "query", "description": "Maximum number of users to return.", "required": false, "type": "integer", "minimum": 1 }, { "name": "sort", "in": "query", "description": "A comma-separated list of sort criteria. The order of the items determines the sorting sequence. The list entries must have the following format: property:sort_direction. Valid values are: 'user_id:asc', 'user_id:desc', 'email:asc', 'email:desc', 'given_name:asc', 'given_name:desc', 'family_name:asc', 'family_name:desc', 'last_access_date:asc', 'last_access_date:desc', 'creation_time:asc', 'creation_time:desc'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "user_id:asc", "user_id:desc", "email:asc", "email:desc", "given_name:asc", "given_name:desc", "family_name:asc", "family_name:desc", "last_access_date:asc", "last_access_date:desc", "creation_time:asc", "creation_time:desc" ] }, "collectionFormat": "csv", "default": "user_id:asc" }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'details', 'groups'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "details", "groups" ] }, "collectionFormat": "csv" }, { "name": "type", "in": "query", "description": "A comma-separated list of user types to be returned in the response object. If no types are specified all types are returned. Valid values are: 'regular_users', 'service_credentials', 'external_users'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "regular_users", "service_credentials", "external_users" ] }, "collectionFormat": "csv" } ], "responses": { "200": { "description": "The request was processed successfully and returned a list of user objects that match the specified query parameters.", "schema": { "$ref": "#/definitions/users_result" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "post": { "summary": "Invite a new user to the subscription.", "description": "Invites a new user to the subscription. Only account administrators are authorized to perform this call.", "operationId": "inviteUser", "tags": [ "User Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "user", "in": "body", "description": "The user you want to invite to the subscription.", "required": true, "schema": { "$ref": "#/definitions/user_request" } }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'details', 'groups'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "details", "groups" ] }, "collectionFormat": "csv" }, { "name": "activate_automatically", "in": "query", "description": "Use for SAML authentication only. Parameter to activate user automatically on the subscription. Set the value to 'true' and use it with the 'skip_email' parameter set to 'true'.", "required": false, "default": false, "type": "boolean" }, { "name": "skip_email", "in": "query", "description": "Skip sending the invitation email that contains the activation token.", "required": false, "default": false, "type": "boolean" } ], "responses": { "201": { "description": "The request was processed successfully and returned the invited user.", "schema": { "$ref": "#/definitions/user" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "Conflicting values exist for user properties, for example, the user already exists on this subscription with a different family name.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/users/{user_id}": { "get": { "summary": "Get a user by user ID.", "description": "Get the user with the specified user ID. Only account administrators and the requested user in person are authorized to perform this call.", "operationId": "getUser", "tags": [ "User Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "user_id", "in": "path", "description": "Mandatory parameter that specifies the user's ID as stored in the subscription.", "required": true, "type": "string" }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'details', 'groups'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "details", "groups" ] }, "collectionFormat": "csv" } ], "responses": { "200": { "description": "The request was processed successfully and returned the requested user.", "schema": { "$ref": "#/definitions/user" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The requested user cannot be found.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "put": { "summary": "Update the user with the specified user ID.", "description": "Updates the details for a given user. Only account administrators are authorized to perform this call.", "operationId": "updateUser", "tags": [ "User Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "user_id", "in": "path", "description": "Mandatory parameter that specifies the user's ID as stored in the subscription.", "required": true, "type": "string" }, { "name": "user", "in": "body", "required": true, "description": "Mandatory parameter that contains the updated user data.", "schema": { "$ref": "#/definitions/user_request" } }, { "name": "update_mode", "in": "query", "description": "Parameter that specifies how user data is updated. Valid values are: 'replace' for a full update and 'merge' for a partial update.", "required": false, "type": "string", "enum": [ "replace", "merge" ], "default": "replace" }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'details', 'groups'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "details", "groups" ] }, "collectionFormat": "csv" } ], "responses": { "200": { "description": "The request was processed successfully and returned the updated user details.", "schema": { "$ref": "#/definitions/user" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The requested user cannot be found.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "Conflicting values exist for user properties, for example, the email has been changed.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "delete": { "summary": "Delete the user with the specified user ID from the subscription.", "description": "Deletes the specified user from the subscription. Only account administrators are authorized to perform this call.", "operationId": "deleteUser", "tags": [ "User Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "user_id", "in": "path", "description": "Mandatory parameter that specifies the user's ID as stored in the subscription.", "required": true, "type": "string" }, { "name": "keep_bpm_user_data", "in": "query", "description": "Specifies whether workflow user data is removed when the user is deleted. By default, all workflow user data is removed.", "required": false, "type": "boolean", "default": false } ], "responses": { "204": { "description": "The request was processed successfully and deleted the user." }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/users/{user_id}/password": { "put": { "summary": "Update the password of the user with the specified user ID.", "description": "Updates the password for a given user. Only the user himself is authorized to perform this call.", "operationId": "updateUserPassword", "tags": [ "User Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "user_id", "in": "path", "description": "Mandatory parameter that specifies the user's ID as stored in the subscription.", "required": true, "type": "string" }, { "name": "password", "in": "body", "required": true, "description": "Mandatory parameter that contains the updated password information.", "schema": { "$ref": "#/definitions/user_password" } } ], "responses": { "204": { "description": "The request was processed successfully and updated the user's password." }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The requested user cannot be found.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "Conflicting values exist for user properties, for example, the password does not meet the password policy rules.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/groups": { "get": { "summary": "Retrieve a list of groups for this subscription.", "description": "Gets a list of groups for this subscription. Only account administrators are authorized to perform this call.", "operationId": "getGroupsList", "tags": [ "Group Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "search_term", "in": "query", "description": "An optional parameter to search for a group. If set, the call returns groups where the search term is contained in the group ID or display name. The parameter does not support wildcards and it is not case sensitive.", "required": false, "type": "string" }, { "name": "offset", "in": "query", "description": "The number of entries to skip in the query result set before returning an entry. For example, if the offset is 2, entries are returned starting from the third entry in the result set.", "required": false, "type": "integer", "default": 0, "minimum": 0 }, { "name": "size", "in": "query", "description": "Maximum number of groups to return.", "required": false, "type": "integer", "minimum": 1 }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'members', 'member_count'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "members", "member_count" ] }, "collectionFormat": "csv" } ], "responses": { "200": { "description": "The request was processed successfully and returned a list of group objects that match the specified query parameters.", "schema": { "$ref": "#/definitions/groups_result" } }, "400": { "description": "The request contains invalid parameters, or required parameters are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "post": { "summary": "Create a new group on the subscription.", "description": "Creates a new group on the subscription. Only account administrators are authorized to perform this call.", "operationId": "createGroup", "tags": [ "Group Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "group", "in": "body", "description": "The group you want to create on the subscription.", "required": true, "schema": { "$ref": "#/definitions/group_input" } }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'members', 'member_count'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "members", "member_count" ] }, "collectionFormat": "csv" } ], "responses": { "201": { "description": "The request was processed successfully and it returned the new group.", "schema": { "$ref": "#/definitions/group" } }, "400": { "description": "The request contains invalid parameters, or required parameters are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "Conflicting values exist for group properties, for example, the group already exists on this subscription.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/groups/{name}": { "get": { "summary": "Get a group by name.", "description": "Get the group with the specified name. Only account administrators are authorized to perform this call.", "operationId": "getGroup", "tags": [ "Group Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "name", "in": "path", "description": "Mandatory parameter that specifies the group's name as stored in the subscription.", "required": true, "type": "string" }, { "name": "base_dn", "in": "query", "description": "Optional parameter to define the group's base name in the LDAP repository if the name is different from the configured default.", "required": false, "type": "string" }, { "name": "optional_parts", "in": "query", "description": "A comma-separated list of optional parts to be returned in the response object. If no parts are specified, only the base object is returned. Valid values are: 'members', 'member_count'.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "members", "member_count" ] }, "collectionFormat": "csv" } ], "responses": { "200": { "description": "The request was processed successfully and returned the requested group.", "schema": { "$ref": "#/definitions/group" } }, "400": { "description": "The request contains invalid parameters, or required parameters are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The requested group cannot be found.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "delete": { "summary": "Delete the group with the specified name from the subscription.", "description": "Deletes the specified group from the subscription. Only account administrators are authorized to perform this call.", "operationId": "deleteGroup", "tags": [ "Group Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "name", "in": "path", "description": "Mandatory parameter that specifies the group's name as stored in the subscription.", "required": true, "type": "string" }, { "name": "base_dn", "in": "query", "description": "Optional parameter to define the group's base name in the LDAP repository if the name is different from the configured default.", "required": false, "type": "string" } ], "responses": { "204": { "description": "The request was processed successfully and the group was deleted." }, "400": { "description": "The request contains invalid parameters, or required parameters are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The group can not be deleted due to a conflict, for example, the group is a default group.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/groups/{name}/members": { "post": { "summary": "Add members to a group on the subscription.", "description": "Adds members to a group on the subscription. Only account administrators are authorized to perform this call.", "operationId": "addMembers", "tags": [ "Group Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "name", "in": "path", "description": "Mandatory parameter that specifies the group's name as stored in the subscription.", "required": true, "type": "string" }, { "name": "base_dn", "in": "query", "description": "Optional parameter to define the group's base name in the LDAP repository if the name is different from the configured default.", "required": false, "type": "string" }, { "name": "members", "in": "body", "description": "The members to add to the group.", "required": true, "schema": { "$ref": "#/definitions/group_members" } } ], "responses": { "201": { "description": "The request was processed successfully. The response contains the updated member list.", "schema": { "$ref": "#/definitions/group_members" } }, "400": { "description": "The request contains invalid parameters, or required parameters are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The requested group cannot be found.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "You've exceeded the maximum number of allowed users for this group", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "put": { "summary": "Change the members of a group on the subscription.", "description": "Makes a full replace of members in a group on the subscription. Only account administrators are authorized to perform this call.", "operationId": "changeMembers", "tags": [ "Group Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "name", "in": "path", "description": "Mandatory parameter that specifies the group's name as stored in the subscription.", "required": true, "type": "string" }, { "name": "base_dn", "in": "query", "description": "Optional parameter to define the group's base name in the LDAP repository if the name is different from the configured default.", "required": false, "type": "string" }, { "name": "members", "in": "body", "description": "The members of the group.", "required": true, "schema": { "$ref": "#/definitions/group_members" } } ], "responses": { "200": { "description": "The request was processed successfully. The response contains the updated member list.", "schema": { "$ref": "#/definitions/group_members" } }, "400": { "description": "The request contains invalid parameters, or required parameters are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "You've exceeded the maximum number of allowed users for this group", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "delete": { "summary": "Remove members from the group on the subscription.", "description": "Removes members from the group on the subscription. Only account administrators are authorized to perform this call.", "operationId": "removeMembers", "tags": [ "Group Management" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "name", "in": "path", "description": "Mandatory parameter that specifies the group's name as stored in the subscription.", "required": true, "type": "string" }, { "name": "base_dn", "in": "query", "description": "Optional parameter to define the group's base name in the LDAP repository if the name is different from the configured default.", "required": false, "type": "string" }, { "name": "members", "in": "body", "description": "The members to remove from the group.", "required": true, "schema": { "$ref": "#/definitions/group_members" } } ], "responses": { "200": { "description": "The request was processed successfully. The response contains the updated member list.", "schema": { "$ref": "#/definitions/group_members" } }, "400": { "description": "The request contains invalid parameters, or required parameters are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/reports": { "get": { "summary": "Get report data for the specified time period.", "description": "Get report data for the specified time period.", "operationId": "getReport", "tags": [ "Reports" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "start_day", "in": "query", "description": "The start date for retrieving report data.", "type": "string", "format": "date", "required": true }, { "name": "days", "in": "query", "description": "The number of days to include in the report relative to the 'start_day'. To return data for days before the specified date, specify a negative value. To return data for days after the specified date, specify a positive value. If a value is not specified, only the start day's metrics are returned.", "type": "integer", "default": 1, "minimum": -365, "maximum": 365 }, { "name": "metric", "in": "query", "description": "Specifies which metric to retrieve. Retrieve valid values by using the /metrics call.", "type": "string", "required": true }, { "name": "environment", "in": "query", "description": "The operating environment to retrieve the data from, for example, 'dev' for the development environment.", "type": "string" } ], "responses": { "200": { "description": "The report data was successfully returned.", "schema": { "$ref": "#/definitions/report_data" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The user is not authorized to view the report data.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/metrics": { "get": { "summary": "Retrieve metrics for the subscription.", "description": "Retrieve a list of report metrics for the subscription.", "operationId": "getMetrics", "tags": [ "Reports" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The request was processed successfully and returned a list of report metrics.", "schema": { "$ref": "#/definitions/metrics_result" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/audit_events": { "get": { "summary": "Retrieve a list of audit events for this subscription.", "description": "Gets a list of audit events for this subscription. Only account administrators are authorized to perform this call.", "operationId": "getAuditEventList", "tags": [ "Audit Events" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "start_day", "in": "query", "description": "The start date for retrieving audit events.", "type": "string", "format": "date", "required": true }, { "name": "days", "in": "query", "description": "The number of days to include in the audit events retrieval relative to the 'start_day'. To return data for days before the specified date, specify a negative value. To return data for days after the specified date, specify a positive value. If a value is not specified, only the start day's events are returned.", "type": "integer", "default": 1, "minimum": -365, "maximum": 365 }, { "name": "event_types", "in": "query", "description": "A comma-separated list of event types to be returned in the response object. To retrieve a set of events, use asterisk (*) after a prefix. If no types are specified all available types are returned.", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "csv" }, { "name": "offset", "in": "query", "description": "The number of entries to skip in the query result set before returning an entry. For example, if the offset is 2, entries are returned starting from the third entry in the result set.", "required": false, "type": "integer", "default": 0, "minimum": 0 }, { "name": "size", "in": "query", "description": "Maximum number of events to return.", "required": false, "type": "integer", "minimum": 1 } ], "responses": { "200": { "description": "The request was processed successfully and returned a list of audit event objects that match the specified query parameters.", "schema": { "$ref": "#/definitions/audit_events_result" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/audit_event_types": { "get": { "summary": "Retrieve a list of available audit event types for this subscription.", "description": "Gets a list of available audit event types for this subscription. Only account administrators are authorized to perform this call.", "operationId": "getAuditEventTypeList", "tags": [ "Audit Events" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The request was processed successfully and returned a list of user objects that match the specified query parameters.", "schema": { "$ref": "#/definitions/audit_event_types" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/logs": { "get": { "summary": "Get the details of all log requests.", "description": "Get the details for all log requests. Operators can retrieve log requests for all environments. Users who can access the development environment can also retrieve log requests for this environment.", "operationId": "getAllLogRequests", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environments", "in": "query", "description": "An optional parameter to filter the returned log requests by the operating environment, for example, 'dev' for the development environment.", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "csv" }, { "name": "offset", "in": "query", "description": "The number of entries to skip in the query result set before returning an entry. For example, if the offset is 2, entries are returned starting from the third entry in the result set.", "required": false, "type": "integer", "default": 0, "minimum": 0 }, { "name": "size", "in": "query", "description": "Maximum number of log requests to return.", "required": false, "type": "integer", "minimum": 1 } ], "produces": [ "application/json" ], "responses": { "200": { "description": "The request was successfully processed and returned all log requests.", "schema": { "$ref": "#/definitions/logs_result" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "post": { "summary": "Request a log.", "description": "Request a log. Operators can request logs for all environments. Users who can access the development environment can also request a log for this environment.", "operationId": "requestLog", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "log_request", "in": "body", "required": true, "description": "Specifies details about the log request.", "schema": { "$ref": "#/definitions/log_request" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "201": { "description": "The request was successfully processed and returned the log request data.", "schema": { "$ref": "#/definitions/log" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/logs/{log_id}": { "get": { "summary": "Get the details of a log request.", "description": "Get the details for a log request ID. Operators can retrieve a log for all environments. Users who can access the development environment can also retrieve a log for this environment.", "operationId": "getLogRequest", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "log_id", "in": "path", "description": "The identifier of the log request.", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "The request was successfully processed and returned the log request data.", "schema": { "$ref": "#/definitions/log" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The log request with the specified ID does not exist.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "delete": { "summary": "Delete a log request and log file.", "description": "Delete the log request and log file. Operators can delete logs for all environments. Users who can access the development environment can also delete a log for this environment.", "operationId": "deleteLogRequest", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "log_id", "in": "path", "description": "The identifier of the log request.", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "204": { "description": "The log request and its associated data were removed successfully." }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/logs/{log_id}/file": { "get": { "summary": "Download the log file.", "description": "Download the log file. Operators can download log files for all environments. Users who can access the development environment can also download a log file for this environment.", "operationId": "getLogFile", "tags": [ "Log Management" ], "produces": [ "application/zip" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "log_id", "in": "path", "description": "The ID of the log request.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The log file was successfully returned.", "schema": { "type": "file" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The log request with the specified ID does not exist.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The download failed because the log request is still in progress or it failed.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/bulk/logs": { "delete": { "summary": "Delete multiple log requests and their log file.", "description": "Delete multiple log requests and their files according to the specified filter criteria. There must be at least one filter specified. Operators can delete logs for all environments. Users who can access the development environment can also delete a log for this environment.", "operationId": "deleteLogs", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "request_time", "in": "query", "description": "Delete all logs that were requested before this time.", "required": true, "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "The specified logs were successfully deleted.", "schema": { "$ref": "#/definitions/logs" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/log_types": { "get": { "summary": "Retrieve a list of valid log types.", "description": "Get the valid log type values for a log request.", "operationId": "getLogTypes", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "query", "description": "An optional parameter to restrict the query for log types to an operating environment, for example, 'dev' for the development environment.", "required": false, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "The request was successfully processed and returned all log type values.", "schema": { "$ref": "#/definitions/log_types" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/environments/{environment}/log_types/{log_type}/trace_settings": { "get": { "summary": "Get the trace settings of a log type in an enviroment.", "description": "System operators can get the trace settings of a log type in any environment. Users who can access the development environment can also request the trace settings for this environment.", "operationId": "getTraceSettings", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "path", "description": "Parameter that specifies the operating environment for which the trace settings are retrieved, for example, 'dev' for the development environment.", "required": true, "type": "string" }, { "name": "log_type", "in": "path", "description": "Parameter that specifies the log type for which the trace settings are retrieved.", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "The request was successfully processed and the trace settings were returned.", "schema": { "$ref": "#/definitions/trace_settings" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The environment or log type is not defined for the current instance.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "put": { "summary": "Update the trace setting for a given environment and log type.", "description": "System operators can modify the trace settings of a log type in any environment. Users who can access the development environment can also modify trace settings for this environment.", "operationId": "updateTraceSettings", "tags": [ "Log Management" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "path", "description": "Parameter that specifies the operating environment for which the trace settings are updated, for example, 'dev' for the development environment.", "required": true, "type": "string" }, { "name": "log_type", "in": "path", "description": "Parameter that specifies the log type for which the trace settings are updated.", "required": true, "type": "string" }, { "name": "trace_settings", "in": "body", "required": true, "description": "Specifies details about the new trace settings.", "schema": { "$ref": "#/definitions/trace_settings" } } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "The request was successfully processed and returned the trace settings.", "schema": { "$ref": "#/definitions/trace_settings" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The environment or log type is not defined in the current instance.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/environments/{environment}/plugins": { "post": { "summary": "Upload a new IBM Content Navigator plug-in.", "description": "Upload a new IBM Content Navigator plug-in to a cloud environment on the subscription.", "operationId": "uploadPlugin", "tags": [ "Application Management" ], "consumes": [ "multipart/form-data" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "path", "description": "Parameter to specify where to upload the plug-in, for example, 'dev' for the development environment.", "required": true, "type": "string" }, { "name": "plugin_name", "in": "formData", "description": "The file name of the IBM Content Navigator plug-in to upload.", "required": true, "type": "string" }, { "name": "jar", "in": "formData", "description": "The IBM Content Navigator plug-in JAR file to upload.", "required": true, "type": "file" } ], "responses": { "202": { "description": "The request to upload the specified plug-in to ICN was submitted. Once the plug-in is uploaded, it will be ready for deployment in IBM Content Navigator Administration desktop.", "schema": { "$ref": "#/definitions/request_accepted_result" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The environment with the specified ID does not exist.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The request cannot be completed because of a conflict with the current state of the resource.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/oauth_clients": { "post": { "description": "Create a new OAuth client credential.", "operationId": "createOAuthCredential", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "credential", "in": "body", "description": "The OAuth client credential to create.", "required": true, "schema": { "$ref": "#/definitions/oauth_credential_request" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "The request was successfully processed and the new OAuth client credential was returned.", "schema": { "$ref": "#/definitions/oauth_credential" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The credential cannot be created because there is already one with this prefix.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "get": { "description": "Get all OAuth client credentials for this subscription.", "operationId": "getOAuthCredentials", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "offset", "in": "query", "description": "The number of entries to skip in the query result set before returning an entry. For example, if the offset is 2, entries are returned starting from the third entry in the result set.", "required": false, "type": "integer", "default": 0, "minimum": 0 }, { "name": "size", "in": "query", "description": "Maximum number of OAuth client credentials to return.", "required": false, "type": "integer", "minimum": 1 } ], "produces": [ "application/json" ], "responses": { "200": { "description": "The request was successfully processed and returned all OAuth client credentials.", "schema": { "$ref": "#/definitions/oauth_credentials_result" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/oauth_clients/{client_id}": { "delete": { "description": "Delete a OAuth client credential.", "operationId": "deleteOAuthCredential", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "client_id", "in": "path", "description": "The credential to delete.", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "204": { "description": "The request was successfully processed and the credential was deleted." }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/service_credentials": { "post": { "description": "Create a new service credential.", "operationId": "createServiceCredential", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "credential", "in": "body", "description": "The service credential to create.", "required": true, "schema": { "$ref": "#/definitions/service_credential_request" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "The request was successfully processed and the new service credential was returned.", "schema": { "$ref": "#/definitions/service_credential_result" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The credential cannot be created because there is already one with this prefix.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } }, "get": { "description": "Get all service credentials for the subscription.", "operationId": "getServiceCredentials", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "search_term", "in": "query", "description": "An optional parameter to search for service credentials. If set the call returns service credentials where the search term is contained in the ID or description. The parameter does not support wildcards and is case insensitive.", "type": "string", "required": false }, { "name": "offset", "in": "query", "description": "The number of entries to skip in the query result set before returning an entry. For example, if the offset is 2, entries are returned starting from the third entry in the result set.", "required": false, "type": "integer", "default": 0, "minimum": 0 }, { "name": "size", "in": "query", "description": "Maximum number of service credentials to return.", "required": false, "type": "integer", "minimum": 1 }, { "name": "sort", "in": "query", "description": "The sort criteria.", "required": false, "type": "string", "enum": [ "id:asc", "id:desc", "description:asc", "description:desc", "creator:asc", "creator:desc", "creation_time:asc", "creation_time:desc", "last_modifier:asc", "last_modifier:desc", "last_modification_time:asc", "last_modification_time:desc" ] } ], "produces": [ "application/json" ], "responses": { "200": { "description": "The request was successfully processed and returned the requested service credentials.", "schema": { "$ref": "#/definitions/service_credentials_result" } }, "400": { "description": "The request contains invalid parameters, or they are missing.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/service_credentials/{service_credential_id}/password": { "put": { "tags": [ "Credentials" ], "description": "Regenerate the password for a service credential", "operationId": "regenerateServiceCredentialPassword", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "service_credential_id", "in": "path", "description": "The service credential to change.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The request was processed successfully and updated the functional id's password.", "schema": { "$ref": "#/definitions/service_credential_result" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The credential with specified ID was not found for the subscription.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/service_credentials/{service_credential_id}": { "delete": { "description": "Delete a service credential.", "operationId": "deleteServiceCredential", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "service_credential_id", "in": "path", "description": "The service credential to delete.", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "204": { "description": "The request was successfully processed and the credential was deleted." }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/service_credentials/{service_credential_id}/import": { "post": { "description": "Import a service credential from another subscription.", "operationId": "importServiceCredential", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "service_credential_id", "in": "path", "description": "The service credential to import.", "required": true, "type": "string" }, { "name": "credential", "in": "body", "description": "The import details to apply.", "required": true, "schema": { "$ref": "#/definitions/service_credential_import_request" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "The request was successfully processed and the imported credential was returned.", "schema": { "$ref": "#/definitions/service_credential_result" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The credential with specified ID was not found for the subscription implied by the import token.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The credential cannot be imported because it already exists on the subscription.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/import_tokens": { "post": { "description": "Create a new import token to authorize the import of the specified credential on another subscription.", "operationId": "createImportToken", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "import_token", "in": "body", "description": "The import token details.", "required": true, "schema": { "$ref": "#/definitions/import_token_request" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "The request was successfully processed and the new import token was returned.", "schema": { "$ref": "#/definitions/import_token_result" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The service credential with specified ID was not found for the subscription.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "The service credential with specified ID cannot be shared.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/credentials/import_tokens/{import_token_value}": { "delete": { "description": "Delete an import token.", "operationId": "deleteImportToken", "tags": [ "Credentials" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "import_token_value", "in": "path", "description": "The value of the import token to delete.", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "204": { "description": "The request was successfully processed and the import token was deleted." }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/version": { "get": { "summary": "Retrieve version information.", "description": "Retrieve version information for the Cloud Pak for Business Automation as a Service components.", "operationId": "getVersion", "tags": [ "Version" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" } ], "responses": { "200": { "description": "The request was processed successfully and returned the version information.", "schema": { "$ref": "#/definitions/version" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/environments/{environment}/certificates": { "get": { "summary": "Get a list of currently used certificates.", "description": "Get a list of certificates. Operators who have access to the environment are allowed to perform this call.", "operationId": "getCertificate", "tags": [ "Certificates" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "path", "description": "The environment ID for which the certificates are requested.", "required": true, "type": "string" }, { "name": "offset", "in": "query", "description": "The number of entries to skip in the query result set before returning an entry. For example, if the offset is 2, entries are returned starting from the third entry in the result set.", "required": false, "type": "integer", "default": 0, "minimum": 0 }, { "name": "size", "in": "query", "description": "Maximum number of certificates to return.", "required": false, "type": "integer", "minimum": 1 } ], "responses": { "200": { "description": "The request was processed successfully and returned the list of certificates.", "schema": { "$ref": "#/definitions/certificates_response" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The environment with the specified ID does not exist.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/environments/{environment}/certificates/import": { "post": { "summary": "Import a new certificate.", "description": "Import a new certificates. Operators who have access to the environment are allowed to perform this call.", "operationId": "importCertificate", "tags": [ "Certificates" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "path", "description": "The environment ID for where to import the certificate.", "required": true, "type": "string" }, { "name": "import_certificate", "in": "body", "description": "The import certificates details.", "required": true, "schema": { "$ref": "#/definitions/import_certificate_request" } } ], "responses": { "201": { "description": "The request was processed successfully and returned the new certificate.", "schema": { "$ref": "#/definitions/certificate" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The environment with the specified ID does not exist.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "You cannot create a certificate with alias that already exists or an alias starting with a reserved prefix.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/environments/{environment}/certificates/from_file": { "post": { "summary": "Add a new certificate from file.", "description": "Add a new certificates from a certificate file. Operators who have access to the environment are allowed to perform this call.", "operationId": "addCertificateFromFile", "tags": [ "Certificates" ], "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "path", "description": "The environment ID for where to import the certificate.", "required": true, "type": "string" }, { "name": "alias", "in": "formData", "description": "The alias for the certificate.", "required": true, "type": "string" }, { "name": "cert_file", "in": "formData", "description": "The certificate file must be in PEM format.", "required": true, "type": "file" } ], "responses": { "201": { "description": "The request was processed successfully and returned the new certificate.", "schema": { "$ref": "#/definitions/certificate" } }, "400": { "description": "Invalid input.", "schema": { "$ref": "#/definitions/exception" } }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "404": { "description": "The environment with the specified ID does not exist.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "You cannot create a certificate with alias that already exists or an alias starting with a reserved prefix.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } }, "/environments/{environment}/certificates/{alias}": { "delete": { "summary": "Delete the certificate in the specified environment.", "description": "Delete a certificate. Operators who have access to the environment are allowed to perform this call.", "operationId": "deleteCertificate", "tags": [ "Certificates" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "name": "IBM-CSRF-TOKEN", "in": "header", "description": "The REST API token for cross-site request forgery (CSRF) prevention.", "required": true, "type": "string" }, { "name": "environment", "in": "path", "description": "The environment ID where the certificate is deleted.", "required": true, "type": "string" }, { "name": "alias", "in": "path", "type": "string", "description": "The alias of the certificate to be deleted.", "required": true } ], "responses": { "204": { "description": "The request was processed successfully and the certificate was deleted." }, "403": { "description": "The caller is not authorized to perform the request.", "schema": { "$ref": "#/definitions/exception" } }, "409": { "description": "You cannot delete a certificate starting with a reserved prefix.", "schema": { "$ref": "#/definitions/exception" } }, "500": { "description": "Internal server error.", "schema": { "$ref": "#/definitions/exception" } } } } } }, "produces": [ "application/json" ], "securityDefinitions": { "basic_auth": { "type": "basic" } }, "definitions": { "csrf_request": { "title": "Cross-site request forgery (CSRF) protection request", "description": "Request object for creating a new CSRF token", "properties": { "requested_lifetime": { "description": "The lifetime of the requested token in seconds (positive integer). The value must be smaller than or equal to the maximum lifetime value of 7200.", "type": "integer", "default": 7200, "minimum": 1, "format": "int32" } } }, "csrf_token": { "title": "Cross-site request forgery (CSRF) protection token", "description": "A token required by REST APIs to prevent (CSRF) attacks.", "properties": { "csrf_token": { "type": "string" }, "expiration": { "type": "integer" } } }, "hpel_extension_filter": { "description": "Used to filter trace statements.", "required": [ "name", "value" ], "properties": { "name": { "description": "The name of the High Performance Extensible Logging (HPEL) filter.", "type": "string" }, "value": { "description": "The value of the High Performance Extensible Logging (HPEL) filter.", "type": "string" } } }, "log_request": { "description": "Details about the log retrieval request, such as the start time.", "required": [ "environment", "log_type" ], "properties": { "environment": { "description": "The operating environment to retrieve the log from.", "type": "string" }, "log_type": { "description": "The type of log to retrieve. Use the /log_types API to retrieve a list of valid values and supported properties.", "type": "string" }, "start_time": { "description": "The start time to use for the log retrieval request. If not set, the time of the request will be used for log types that support this property.", "type": "string", "format": "date-time" }, "duration": { "description": "The timeframe in minutes for the duration of the log. If not set, the default will be used for log types that support this property.", "type": "integer", "minimum": 1, "maximum": 2880, "default": 15 }, "min_log_level": { "description": "The minimum log level to be retrieved. If not set, the default will be used for log types that support this property.", "type": "string", "default": "all", "enum": [ "all", "finest", "finer", "fine", "detail", "config", "info", "audit", "warning", "severe", "fatal" ] }, "thread": { "description": "The name of the thread (hex value) for which the log is retrieved. If not set, no filter will be applied for log types that support this property.", "type": "string" }, "loggers": { "description": "List of loggers for which the log is retrieved. If not set, no filter will be applied for log types that support this property.", "type": "array", "items": { "type": "string" } }, "hpel_extensions": { "description": "List of High Performance Extensible Logging (HPEL) extension features to restrict the set of log statements. If not set, no filter will be applied for log types that support this property.", "type": "array", "items": { "$ref": "#/definitions/hpel_extension_filter" } } } }, "log": { "description": "Describes a log retrieval request.", "required": [ "log_id", "user_id", "request_time", "state", "log_spec" ], "properties": { "log_id": { "description": "The identifier of the log request.", "type": "string" }, "user_id": { "description": "The unique ID of the user who requested the log.", "type": "string" }, "status": { "description": "The status of the log request, that is, whether the log is available or still in progress.", "type": "string", "enum": [ "in_progress", "failed", "available" ] }, "request_time": { "description": "The time when the log was requested.", "type": "string", "format": "date-time" }, "log_request": { "$ref": "#/definitions/log_request" } } }, "logs": { "description": "List of log requests.", "properties": { "logs": { "type": "array", "items": { "$ref": "#/definitions/log" } } } }, "logs_result": { "description": "List of log requests.", "required": [ "logs" ], "properties": { "logs": { "type": "array", "items": { "$ref": "#/definitions/log" } }, "total_size": { "description": "The total number of log requests", "type": "integer" }, "previous": { "type": "string", "description": "A URL that returns the previous page of logs." }, "next": { "type": "string", "description": "A URL that returns the next page of logs." } } }, "log_types": { "description": "A list of log types.", "required": [ "log_types" ], "properties": { "log_types": { "type": "array", "items": { "$ref": "#/definitions/log_type" } } } }, "log_type": { "description": "A list of log types.", "required": [ "type", "name", "supported_properties" ], "properties": { "type": { "description": "The type identifier to use for retrieving logs.", "type": "string" }, "name": { "description": "The language-specific name of the type.", "type": "string" }, "customizable_trace": { "description": "Specifies whether the log type allows changing the trace specification.", "type": "boolean" }, "supported_properties": { "description": "The list of supported properties for a log request with this type. Valid values are: 'start_time', 'duration', 'min_log_level', 'thread', 'loggers', 'hpel_extensions'.", "type": "array", "items": { "type": "string", "enum": [ "start_time", "duration", "min_log_level", "thread", "loggers", "hpel_extensions" ] } } } }, "trace_settings": { "description": "Trace settings of a given component or log type in an environment", "required": [ "trace_specification" ], "properties": { "trace_specification": { "description": "The trace specification.", "type": "string" } } }, "exception": { "description": "An exception object that describes the details of the REST API error.", "required": [ "error_number", "error_message" ], "properties": { "error_number": { "type": "string", "description": "The message ID of the exception." }, "error_message": { "type": "string", "description": "The message text of the exception." }, "error_message_parameters": { "type": "array", "items": { "type": "string", "description": "An array of parameter strings that were inserted into the error message." }, "description": "Message text parameters for the exception." }, "error_cause": { "$ref": "#/definitions/exception" }, "error_details": { "type": "object", "description": "Additional details to clarify the exception." }, "incident_id": { "type": "string", "description": "Unique identifier of the exception. An authorized user can use the incident ID to locate the details of the exception in the server's messages.log file." } } }, "user_bulk_result": { "description": "The result of a bulk request.", "required": [ "success" ], "properties": { "success": { "type": "array", "items": { "$ref": "#/definitions/user" }, "description": "A list of user that were successfully processed." }, "failures": { "type": "array", "items": { "$ref": "#/definitions/user_bulk_failure" }, "description": "A list of users that could not be processed and details of the reasons." } } }, "user_bulk_failure": { "description": "The data structure for reporting the results of user bulk actions that were not successful.", "properties": { "user": { "description": "The user for which the processing failed.", "$ref": "#/definitions/user_request" }, "cause": { "description": "The reason why the processing failed.", "type": "object" } } }, "users": { "description": "A list of user objects.", "required": [ "users" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/definitions/user_request" } } } }, "users_result": { "description": "A list of user objects.", "required": [ "users" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/definitions/user" } }, "total_size": { "type": "integer", "description": "The total number of users available." }, "previous": { "type": "string", "description": "A URL that returns the previous page of users." }, "next": { "type": "string", "description": "A URL that returns the next page of users." } } }, "user_request": { "description": "Information about a user to be created.", "required": [ "user_id" ], "properties": { "user_id": { "description": "The unique ID of the user as stored on the subscription.", "type": "string" }, "base_dn": { "description": "The users base name in the LDAP repository. By default, the configured base name is used.", "type": "string" }, "email": { "description": "The email address of the user. If the email address isn't available, the user ID is used for the email address.", "type": "string" }, "given_name": { "description": "The given name of the user.", "type": "string" }, "family_name": { "description": "The family name of the user.", "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/definitions/user_group" } }, "details": { "$ref": "#/definitions/user_details" } } }, "user": { "description": "Information about a user.", "required": [ "user_id" ], "properties": { "user_id": { "description": "The unique ID of the user as stored on the subscription.", "type": "string" }, "base_dn": { "description": "The users base name in the LDAP repository. By default, the configured base name is used.", "type": "string" }, "email": { "description": "The email address of the user. If the email address isn't available, the user ID is used for the email address.", "type": "string" }, "given_name": { "description": "The given name of the user.", "type": "string" }, "family_name": { "description": "The family name of the user.", "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/definitions/user_group" } }, "details": { "$ref": "#/definitions/user_details" }, "last_access_date": { "description": "The date in UTC when user last accessed the instance.", "type": "string", "format": "date" }, "creation_time": { "description": "The date-time in UTC when user was created in the instance.", "type": "string", "format": "date-time" } } }, "user_details": { "description": "Details about a user.", "properties": { "phone_number": { "description": "The user's telephone number.", "type": "string" }, "preferred_language": { "description": "The user's preferred language.", "type": "string", "default": "en" } } }, "additional_roles": { "description": "The user's additional roles in each environment.", "properties": { "environment": { "description": "The operating environment where the roles are defined.", "type": "string" }, "roles": { "description": "The additional roles", "type": "array", "items": { "type": "string" } } } }, "user_record": { "description": "The full user record of a user.", "properties": { "user": { "$ref": "#/definitions/user" }, "subscriptions": { "type": "array", "items": { "$ref": "#/definitions/user_subscription" } }, "first_login_time": { "description": "The time the user logged into the DBAoC offering for the first time.", "type": "string", "format": "date-time" }, "password_changed_time": { "description": "The time the user last changed password.", "type": "string", "format": "date-time" }, "tools_password_changed_time": { "description": "The time the user last changed the tools password.", "type": "string", "format": "date-time" }, "saml": { "description": "Whether or not the user is federated via SAML.", "type": "boolean" }, "locale": { "description": "The locale to display to the current user.", "type": "string", "default": "en" }, "additional_roles": { "description": "The additional roles the user has in each environment.", "type": "array", "items": { "$ref": "#/definitions/additional_roles" } } } }, "user_group": { "description": "Definition of the group the user is a member of.", "required": [ "name" ], "properties": { "name": { "description": "The name of the group.", "type": "string" }, "base_dn": { "description": "The location of the group in the ldap.", "type": "string" } } }, "user_password": { "description": "Change Password information for a user.", "required": [ "password", "new_password" ], "properties": { "password": { "description": "The current password of the user to authorize the change.", "type": "string" }, "new_password": { "description": "The new password of the user.", "type": "string" }, "activate_only": { "description": "Whether to activate the current password in the subscription repository only.", "default": false, "type": "boolean" }, "terminate_sessions": { "description": "Whether or not to terminate existing login sessions for the user including a short account lock-down.", "default": false, "type": "boolean" } } }, "groups_result": { "description": "A list of group objects.", "required": [ "groups" ], "properties": { "groups": { "type": "array", "items": { "$ref": "#/definitions/group_base" } }, "total_size": { "type": "integer", "description": "The total number of groups available." }, "previous": { "type": "string", "description": "A URL that returns the previous page of groups." }, "next": { "type": "string", "description": "A URL that returns the next page of groups." } } }, "group_input": { "description": "Information about a group.", "required": [ "name" ], "properties": { "name": { "description": "The name of the group.", "type": "string" }, "base_dn": { "description": "The group's base name in the LDAP repository. By default, the configured base name is used.", "type": "string" }, "members": { "description": "The users or groups that are in this group.", "type": "array", "items": { "$ref": "#/definitions/group_member" } } } }, "group_base": { "description": "Information about a group.", "required": [ "name" ], "properties": { "name": { "description": "The name of the group.", "type": "string" }, "base_dn": { "description": "The group's base name in the LDAP repository. By default, the configured base name is used.", "type": "string" }, "members": { "description": "The users or groups that are in this group.", "type": "array", "items": { "$ref": "#/definitions/group_member" } }, "member_count": { "type": "integer", "format": "int64", "description": "The number of members in the group including users and groups." } } }, "group": { "description": "Information about a group.", "required": [ "name" ], "properties": { "name": { "description": "The name of the group.", "type": "string" }, "base_dn": { "description": "The group's base name in the LDAP repository. By default, the configured base name is used.", "type": "string" }, "created_time": { "description": "The time the group was created.", "type": "string", "format": "date-time" }, "modified_time": { "description": "The time the group was modified.", "type": "string", "format": "date-time" }, "members": { "description": "The users or groups that are in this group.", "type": "array", "items": { "$ref": "#/definitions/group_member" } }, "member_count": { "type": "integer", "format": "int64", "description": "The number of members in the group including users and groups." } } }, "group_members": { "description": "A list of group member objects.", "required": [ "group_members" ], "properties": { "group_members": { "type": "array", "items": { "$ref": "#/definitions/group_member" } } } }, "group_member": { "description": "A member of a group.", "required": [ "member_id", "type" ], "properties": { "member_id": { "description": "The unique ID of the user or group.", "type": "string" }, "type": { "description": "The type of the member.", "type": "string", "enum": [ "user", "group" ] }, "base_dn": { "description": "The member's base name in the LDAP repository. By default, the configured base name is used.", "type": "string" } } }, "report_spec": { "title": "The definition of the scope of the usage report to be retrieved, including the time period and other metrics.", "description": "Details of a report", "required": [ "start_day", "metric" ], "properties": { "start_day": { "description": "The start date for the report. You can use the 'days' parameter to define a time period based on the start date.", "type": "string", "format": "date" }, "days": { "description": "The number of days to include in the report relative to the 'start_day'. To return data for days before the specified date, specify a negative value. To return data for days after the specified date, specify a positive value. If a value is not specified, only the start day's metrics are returned.", "type": "integer", "default": 1 }, "metric": { "description": "Specifies which metric the report refers to.", "type": "string", "default": "maximum_concurrent_users" }, "environment": { "description": "Specifies the environment for which the report is requested.", "type": "string" } } }, "report_day_value": { "title": "The metric value per day.", "description": "Specifies the metric value for a day.", "required": [ "day" ], "properties": { "day": { "description": "The day for which the metric is valid.", "type": "string", "format": "date" }, "value": { "description": "The metric value for the specified day.", "type": "integer" } } }, "report_data": { "description": "The returned report data, including metric values per day.", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/report_day_value" } }, "report_spec": { "$ref": "#/definitions/report_spec" }, "statistics": { "$ref": "#/definitions/report_stats" } } }, "report_stats": { "title": "The statistics for the retrieved report.", "description": "Gives the statistics for the retrieved report.", "required": [ "day" ], "properties": { "total": { "description": "The total number or reported values for the retrieved report.", "type": "integer", "format": "int64" }, "minimum": { "description": "The minimum value of reported values for the retrieved report.", "type": "integer" }, "maximum": { "description": "The maximum value of reported values for the retrieved report.", "type": "integer" }, "average": { "description": "The average value of reported values for the retrieved report.", "type": "integer" }, "median": { "description": "The median value of reported values for the retrieved report.", "type": "integer" } } }, "metrics_result": { "description": "A list of report metrics.", "required": [ "metrics" ], "properties": { "metrics": { "type": "array", "items": { "$ref": "#/definitions/metric" } } } }, "metric": { "description": "Details of a metric.", "required": [ "metric", "name", "description", "metric_scope" ], "properties": { "metric": { "description": "The metric identifier to use for retrieving the report.", "type": "string" }, "name": { "description": "The language-specific name of the metric.", "type": "string" }, "description": { "description": "The language-specific description of the metric.", "type": "string" }, "metric_scope": { "description": "Specifies the scope of the metric. Valid values are: 'single_environment', 'all_environments'.", "type": "array", "items": { "type": "string", "enum": [ "single_environment", "all_environments" ] } } } }, "password_policy": { "description": "The password policy rules.", "properties": { "max_repeated_characters": { "type": "integer" }, "min_lower_case_characters": { "type": "integer" }, "min_upper_case_characters": { "type": "integer" }, "min_special_characters": { "type": "integer" }, "allowed_special_characters": { "type": "string" }, "min_alphabetic_characters": { "type": "integer" }, "min_other_characters": { "type": "integer" }, "min_numeric_characters": { "type": "integer" }, "min_length": { "type": "integer" }, "min_history": { "type": "integer" }, "max_failures": { "type": "integer" }, "max_age": { "type": "integer" }, "min_age_in_hours": { "type": "string" } } }, "user_subscription": { "description": "Detailed information about a subscription.", "required": [ "subscription_id", "virtual_host", "display_name" ], "properties": { "subscription_id": { "description": "The ID of the subscription.", "type": "string" }, "virtual_host": { "description": "The virtual host of the subscription.", "type": "string" }, "display_name": { "description": "The display name of the subscription", "type": "string" }, "type": { "description": "Specifies whether this is a BPM, ODM, BACS, BAW or a BACA subscription.", "type": "string", "enum": [ "BPM", "ODM", "BACS", "BAW", "BACA", "DBA", "ACA" ] }, "trial_expiration_time": { "description": "The time when the trial on this subscription expires.", "type": "string", "format": "date-time" }, "trial_extension_allowed": { "description": "Whether the user is allowed to extend their trial period.", "type": "boolean" } } }, "audit_events_result": { "description": "A list of audit event objects.", "required": [ "audit_events" ], "properties": { "audit_events": { "type": "array", "items": { "$ref": "#/definitions/audit_event" } }, "total_size": { "type": "integer", "description": "The total number of events available." }, "previous": { "type": "string", "description": "A URL that returns the previous page of events." }, "next": { "type": "string", "description": "A URL that returns the next page of events." } } }, "audit_event": { "description": "Detailed information about an audit event.", "required": [ "event_time", "event_type", "user_id", "message" ], "properties": { "event_time": { "description": "The time when the event occured.", "type": "string", "format": "date-time" }, "event_type": { "description": "The type of event that occured.", "type": "string" }, "user_id": { "description": "The user that performed the action that caused the event.", "type": "string" }, "message": { "description": "The full message for the event.", "type": "string" } } }, "audit_event_types": { "description": "A list of audit event types.", "required": [ "audit_event_types" ], "properties": { "audit_event_types": { "type": "array", "items": { "type": "string" } } } }, "request_accepted_result": { "description": "The result for a request that was accepted for processing, but the processing has not completed.", "type": "object", "properties": { "description": { "type": "string", "description": "Details about the accepted request." }, "url": { "type": "string", "description": "A URL to verify the progress of the action." } } }, "oauth_credential_request": { "description": "The object used to create a new OAuth client credential.", "required": [ "id_prefix" ], "properties": { "id_prefix": { "description": "The prefix identifier for the OAuth client credential.", "type": "string" }, "description": { "description": "The description of the credential.", "type": "string" } } }, "oauth_credential": { "description": "A credential object that results from the creation request.", "required": [ "client_id", "creator", "creation_time" ], "properties": { "client_id": { "description": "The identifier for the credential that is generated from the prefix the user entered and the cloud subscription ID.", "type": "string" }, "client_secret": { "description": "The OAuth client secret. The client_secret is only returned upon credential creation.", "type": "string" }, "description": { "description": "The description of the credential.", "type": "string" }, "creator": { "description": "The user who created the credential.", "type": "string" }, "creation_time": { "description": "The time when the credential was created.", "type": "string", "format": "date-time" } } }, "oauth_credentials_result": { "description": "The result object that contains all OAuth client credentials.", "required": [ "credentials" ], "properties": { "credentials": { "type": "array", "items": { "$ref": "#/definitions/oauth_credential" } }, "total_size": { "type": "integer", "description": "The total number of OAuth client credentials available." }, "previous": { "type": "string", "description": "A URL that returns the previous page of OAuth client credentials." }, "next": { "type": "string", "description": "A URL that returns the next page of OAuth client credentials." } } }, "service_credential_import_request": { "description": "The object used to import a service credential.", "required": [ "import_token_value", "description" ], "properties": { "import_token_value": { "description": "The import token to authorize the import of the specified service credential.", "type": "string" }, "description": { "description": "The description to be associated with the imported credential.", "type": "string" } } }, "import_token_request": { "description": "The object used to create a new import token.", "required": [ "service_credential_id" ], "properties": { "service_credential_id": { "description": "The id of the service credential for which an import token is requested.", "type": "string" } } }, "import_token_result": { "description": "A token object that results from the creation request.", "required": [ "value", "expires_in", "creation_time", "service_credential_id" ], "properties": { "value": { "description": "The value of the token.", "type": "string" }, "expires_in": { "description": "The time after which the token expires.", "type": "string" }, "creation_time": { "description": "The time when the token was created.", "type": "string", "format": "date-time" }, "service_credential_id": { "description": "The service credential the token refers to.", "type": "string" } } }, "service_credential_request": { "description": "The object used to create a service credential.", "required": [ "prefix" ], "properties": { "prefix": { "description": "The prefix to use when constructing the service credential id.", "type": "string" }, "description": { "description": "The description to be associated with the credential.", "type": "string" } } }, "service_credential_result": { "description": "The result object that contains the service credential details.", "required": [ "id", "description", "creator", "creation_time" ], "properties": { "id": { "description": "The id of the service credential.", "type": "string" }, "secret": { "description": "The service credential secret.", "type": "string" }, "description": { "description": "The description of the service credential.", "type": "string" }, "creator": { "description": "The user who created the service credential.", "type": "string" }, "creation_time": { "description": "The time when the service credential was created.", "type": "string", "format": "date-time" }, "last_modifier": { "description": "The user who most recently modified the service credential.", "type": "string" }, "last_modification_time": { "description": "The time when the service credential was most recently modified.", "type": "string", "format": "date-time" } } }, "service_credentials_result": { "description": "The result object that contains all service credentials.", "required": [ "credentials" ], "properties": { "credentials": { "type": "array", "items": { "$ref": "#/definitions/service_credential_result" } }, "total_size": { "type": "integer", "description": "The total number of credentials available." }, "previous": { "type": "string", "description": "A URL that returns the previous page of credentials." }, "next": { "type": "string", "description": "A URL that returns the next page of credentials." } } }, "user_trial_mode": { "description": "The expert mode settings for current user.", "required": [ "trial_mode" ], "properties": { "trial_mode": { "description": "The trial mode setting for current user.", "type": "string", "enum": [ "expert", "standard" ] } } }, "trial": { "description": "Information about the trial the user is subscribed to.", "required": [ "activation_time", "expiration_time", "trial_extension_allowed" ], "properties": { "activation_time": { "description": "The time when the user started the trial.", "type": "string", "format": "datetime" }, "expiration_time": { "description": "The time when the trial ends.", "type": "string", "format": "datetime" }, "trial_extension_allowed": { "description": "Whether or not the user is allowed to extend their trial period.", "type": "boolean" } } }, "build_component": { "description": "The IBM Cloud Pak for Business Automation as a Service component.", "required": [ "name", "version", "build_date", "build_number" ], "properties": { "name": { "type": "string", "description": "The name of the component." }, "version": { "type": "string", "description": "The version of the component, for example, v202009." }, "build_date": { "type": "string", "format": "date-time", "description": "The build date of the component." }, "build_number": { "type": "string", "description": "The build number of the component." } } }, "version": { "description": "The IBM Cloud Pak for Business Automation as a Service version.", "required": [ "build_components" ], "properties": { "build_components": { "type": "array", "items": { "$ref": "#/definitions/build_component" } } } }, "fingerprint": { "description": "A fingerprint object.", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "The digest algorithm of the fingerprint." }, "value": { "type": "string", "description": "The hex value of the fingerprint." } } }, "certificate": { "description": "A certificate stored in the backend capability.", "required": [ "alias" ], "properties": { "alias": { "type": "string", "description": "The alias of the certificate." }, "issued_to": { "type": "string", "description": "The subject (distinguished name) who issued the certificate." }, "issued_by": { "type": "string", "description": "The issuer (distinguished name) of the certificate." }, "valid_from": { "type": "string", "format": "date-time", "description": "The start of the validity period." }, "valid_until": { "type": "string", "format": "date-time", "description": "The end of the validity period." }, "fingerprints": { "type": "array", "items": { "$ref": "#/definitions/fingerprint" }, "description": "The fingerprints of the certificate." }, "serial_number": { "type": "string", "description": "The hex-encoded serial number of the certificate." } } }, "certificates_response": { "description": "The response of a get certificates request.", "required": [ "certificates" ], "properties": { "certificates": { "type": "array", "items": { "$ref": "#/definitions/certificate" } }, "total_size": { "type": "integer", "description": "The total number of certificates available." }, "previous": { "type": "string", "description": "A URL that returns the previous page of certificates." }, "next": { "type": "string", "description": "A URL that returns the next page of certificates." } } }, "import_certificate_request": { "description": "Details about the site where the certificate is retrieved from.", "required": [ "host", "alias" ], "properties": { "alias": { "type": "string", "description": "The alias of the certificate." }, "host": { "type": "string", "description": "The host to retrieve the certificate from." }, "port": { "type": "integer", "default": 443, "description": "The port to retrieve the certificate from, the default is 443." } } } }, "info": { "title": "IBM Cloud Pak for Business Automation as a Service subscription services APIs", "version": "2025.10", "description": "Resources for working with IBM Cloud Pak for Business Automation as a Service subscription artifacts." }, "consumes": [ "application/json" ] }