#%RAML 0.8 title: IDM API baseUri: https://api.covisintlabs.com/idm/v2 protocols: [HTTPS] schemas: - errorResponseSchema: | { "id" : "http://api.covisint.com/schema/errorResponseSchema", "$schema" : "http://json-schema.org/draft-04/schema", "type" : "object", "description" : "Representation of an HTTP 4xx/5xx error response.", "properties" : { "status" : { "type" : "number", "minimum" : 400, "maximum" : 599, "description" : "The HTTP status code.", "required": true }, "apiMessage" : { "type" : "string", "description" : "A helpful, human-readable description of the error, useful for basic diagnostics." }, "apiStatusCode" : { "type" : "string", "description" : "The API-specific status code." } } } traits: - secured: usage: Apply this to any method that needs to be secured description: Requests requires authentication using a bearer token. headers: Authorization: description: Access token that is obtained from the /token endpoint of the oauth API. pattern: ^Bearer .*$ example: Bearer ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk required: true responses: 401: &401 description: Unauthenticated request. This is returned if the access token is missing, invalid, or expired. Access tokens are obtained through the /token endpoint of the Oauth API. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 403: &403 description: Unauthorized request. The requestor is not authorized to perform the requested operation. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema - getResponse: responses: 404: &404 description: The URI requested is invalid or the resource requested does not exist. # substatus codes and error messages are mentioned below: # (If a resource id is a URI parameter) framework:resource:missing - A resource with the following ID was not found: {resourceId} # No message for an invalid URI body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: &500 description: An unknown server error occurred body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema - postResponse: responses: 500: *500 - deleteResponse: responses: 404: *404 500: *500 - putResponse: responses: 404: *404 500: *500 /applications: is: [secured] description: Collection endpoint for application resources /{appId}: is: [secured] uriParameters: appId: description: External Application Id type: number required: true example: 2314 get: description: | ## Get a single application * If the application exists, the service responds with a status code of 200 and includes the single role in the body of the response. is: [getResponse] responses: 200: description: Application successfully retrieved body: application/json: example: | { "data":{ "applications":[ { "applicationID":"SAMPLE-APP001", "description":[ { "lang":"en-US", "text":"Sample Portal" } ], "externalApplicationID":"SAMPLE-PORTAL", "name":[ { "lang":"en-US", "text":"Sample Portal" } ], "passCode":"", "url":"https://sample.portal.covisint.com" } ], "statusCode":200, "subStatusCode":"" } } get: description: | ## Search Applications * Existing applications can be retrieved via query parameters. * If the applications exist, the service responds with a status code of 200 and includes the result in the body of the response. is: [getResponse] queryParameters: externalApplicationID: description: External Application ID type: string required: false responses: 200: description: All applications that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/json: example: | { "data":{ "applications":[ { "applicationID":"SAMPLE-APP001", "description":[ { "lang":"en-US", "text":"Sample Portal" } ], "externalApplicationID":"SAMPLE-PORTAL", "name":[ { "lang":"en-US", "text":"Sample Portal" } ], "passCode":"", "url":"https://sample.portal.covisint.com" } ], "statusCode":200, "subStatusCode":"" } } /audioCaptchas: is: [secured] get: description: | ## Get audio CAPTCHA * This service provides a CAPTCHA audio byte stream in Base64 encoded format. is: [getResponse] responses: 200: description: Audio CAPTCHA was successfully retrieved body: application/json: example: | { "data":{ "statusCode":"200", "subStatusCode":"", "captchaType":"", "captcha":"tYTBo4kHVeoZPCS6uuyizGNgaM......7eevsDqQ5nvhgT4J+FFaOXhv", "captchaID":"11189590" } } post: is: [postResponse] description: | ## Validate audio CAPTCHA * On successful validation of the audio CAPTCHA, the service responds with a status code of 200. body: application/x-www-form-urlencoded: formParameters: captchaid: description: CAPTCHA ID example: 11189590 required: true type: string verificationcode: description: CAPTCHA value entered by the user example: 82500 required: true type: string responses: 200: description: Audio CAPTCHA successfully validated body: application/json: example: | { "data":{ "statusCode":"200", "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 402: description: CAPTCHA validation failed body: application/json: example: | { "data":{ "statusCode":"402", "message":"Invalid CAPTCHA verification code", "subStatusCode":"C402_9" } } /emails: description: Collection endpoint for email resources post: is: [secured, postResponse] description: | ## Send Email --- #### Send Email Invitation * The *template* query parameter is set to *invitation*. * The type of invite sent depends on the *inviteType* form parameter. * If *inviteType=1* (Company), the parent *companyId* form parameter is not required. * For other *inviteType* values, the *companyId* form parameter is required. * The *to* form parameter is mandatory. #### Send Forgot Login ID Email * The *template* query parameter is set to *forgotUserIdByEmail*. * Authorization is not required * The *client_id* header is mandatory for this form. * The *emailAddress* query parameter is also mandatory. * The *companyId*, *inviteType* and *to* form parameters are not required. queryParameters: template: description: | Email Template. If the template is *invitation*, the *Authorization* header is mandatory. If the template is *forgotLoginIdByEmail*, the *client_id* header is mandatory. required: true type: string enum: [ invitation, forgotLoginIdByEmail ] emailAddress: description: | When template is *forgotUserIdByEmail*, the email address to check for login IDs and to send the email to. required: false type: string example: user@example.com maxLength: 1000 headers: Authorization: description: | Access token that is obtained from the /token endpoint of the oauth API. Required when query parameter *template* is *invitation* and optional when *template* is *forgotLoginIdByEmail*. pattern: ^Bearer .*$ example: Bearer ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk required: false client_id: description: Client ID. Required when query paramater *template* is *forgotLoginIdByEmail* and Access token not provided. example: YWb4hgyU657d2YPA9hipc9HUeXR6faGB type: string body: application/x-www-form-urlencoded: formParameters: companyId: description: | The global Covisint organization ID. Required when the template is *invitation*. example: OABC-DEF012345678 required: false type: string inviteType: description: | * New Company: 1 * New Division: 2 * New User: 3 Required when the template is *invitation*. example: 3 required: false type: number minimum: 1 maximum: 3 to: description: | The email address to receive the mail. Required when the template is *invitation*. example: user@example.com required: false type: string responses: 200: description: Invitation was sent successfully body: application/json: example: | With template = "invitation": { "data":{ "statusCode":"200", "message":"Email has been sent successfully.", "subStatusCode":"" } } With template = "forgotLoginIdByEmail": { "data": { "idpUserID": "EXAMPLE_ADMIN", "statusCode": "200", "subStatusCode": "" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"The receiver email address cannot be null.", "subStatusCode":"C400_1" } } 404: description: Email address was not found body: application/json: example: | { "data": { "statusCode": "404", "message": "Email Address not Found", "subStatusCode": "C404_4" } } /imageCaptchas: is: [secured] get: is: [getResponse] description: | ## Get image CAPTCHA * This service provides a CAPTCHA image byte stream in Base64 encoded format. responses: 200: description: Image CAPTCHA was successfully retrieved body: application/json: example: | { "data":{ "statusCode":"200", "subStatusCode":"", "captchaType":"", "captcha":"/tYTBo4kH//VfeozPCS6u......RyzGNgaM7eevsDqQ5nvhgT4J+FF/aOXhv", "captchaID":"11189429" } } post: is: [postResponse] description: | ## Validate image CAPTCHA * On successful validation of the image CAPTCHA, the service responds with a status code of 200. body: application/x-www-form-urlencoded: formParameters: captchaid: description: CAPTCHA ID example: 11189429 required: true type: string verificationcode: description: CAPTCHA value entered by the user example: kkbrp required: true type: string responses: 200: description: Image CAPTCHA successfully validated body: application/json: example: | { "data":{ "statusCode":"200", "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 402: description: CAPTCHA validation failed body: application/octet-stream: example: | { "data":{ "statusCode":"402", "message":"Invalid CAPTCHA verification code", "subStatusCode":"C402_9" } } /organizations: is: [secured] description: Collection endpoint for organization resources /{orgId}: is: [secured] uriParameters: orgId: description: | Organization ID. For the *Add Application to Organization* API, this needs to be the numeric organization ID _(Example: 12345678)_. For the rest, this is the Global Organization ID _(Example: OABC-DEF012345678)_. type: string example: OABC-DEF012345678 required: true /applications: is: [secured] get: is: [getResponse] description: | ## Search organization applications * Existing organization applications can be retrieved via query parameters. * If the applications exist, the service responds with a status code of 200 and includes the result in the body of the response. queryParameters: organizationName: description: Organization name type: string example: Example, Inc. required: false responses: 200: description: Organization applications retrieved successfully body: application/json: example: | { "data":{ "applications":[ { "applicationID":"991605", "externalApplicationID":"", "iconID":"", "url":null } ], "statusCode":200, "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 404: description: Organization does not exist body: application/json: example: | { "data":{ "statusCode":"404", "message":"Company does not exists:OEJA51-DEV04806947", "subStatusCode":"C404_8" } } 423: description: User is suspended or deleted. Application cannot be retrieved. body: application/octet-stream: example: '' post: is: [postResponse] description: | ## Add Application to Organization * On successful addition of the application to the organization, the service responds with a status code of 200. body: application/x-www-form-urlencoded: formParameters: packageId: description: Package ID example: 99103001 required: true type: number responses: 200: description: Application successfully added body: application/octet-stream: example: | { "data": { "statusCode": 200, "subStatusCode": "" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 423: description: Application is already granted body: application/json: example: | { "data": { "statusCode": "423", "message": "Application is already granted.", "subStatusCode": "C423_3" } } 500: description: Error granting package body: application/json: example: | { "data": { "statusCode": "500", "message": "The package to be granted [123] does not exist.", "subStatusCode": "C500_1" } } get: is: [getResponse] description: | ## Get a single organization application * If the application exists, the service responds with a status code of 200 and includes the result in the body of the response. responses: 200: description: Organization details successfully retrieved body: application/json: example: | { "data":{ "company":{ "organizationName":"Example, Inc.", "org_url":"www.example.com" "org_address1":"Suite 1B-201", "org_address2":"123 Main Street", "org_address3":"", "org_cityRegion":"Tucson", "org_stateProvince":"AZ", "org_postalCode":"85705", "org_countryCode":"US", "organizationId":"9876543", "org_dunsNumber":"150483782", "org_phoneNumber":"12123456789", "org_faxNumber":"12129876543", "organizationCOID":"OABC-DEF012345678", }, "statusCode":200, "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } put: is: [putResponse] description: | ## Modify organization details * On successful modification of organization details, the service returns a status code of 200 along with the updated details of the organization in the body of the response. body: application/x-www-form-urlencoded: formParameters: organizationName: description: 'Organization Name' example: Example, Inc. required: false type: string org_url: description: 'Organization URL' example: www.example.com required: false type: string org_address1: description: 'Address Line 1' example: RR 1 Box 68A required: false type: string org_address2: description: 'Address Line 2' example: 16 Willow Dr required: false type: string org_address3: description: 'Address Line 3' example: Willow Farms required: false type: string org_cityRegion: description: 'City' example: Dunley required: false type: string org_stateProvince: description: 'State or Province' example: PA required: false type: string org_postalCode: description: 'Postal Code' example: 15432 required: false type: string org_countryCode: description: 'Country Code' example: US required: false type: string org_phoneNumber: description: 'Phone Number' example: 12123456789 required: false type: string org_faxNumber: description: 'Fax Number' example: 12129876543 required: false type: string org_dunsNumber: description: 'DUNS Number' example: 150483782 required: false type: string responses: 200: description: If the organization exists, the service responds with a status code of 200 and includes the result in the body of the response. body: application/json: example: | { "data":{ "company":{ "organizationName":"Example, Inc.", "org_url":"www.example.com" "org_address1":"RR 1 Box 68A", "org_address2":"16 Willow Dr", "org_address3":"Willow Farms", "org_cityRegion":"Dunley", "org_stateProvince":"PA", "org_postalCode":"15432", "org_countryCode":"US", "org_phoneNumber":"12123456789", "org_faxNumber":"12129876543", "org_dunsNumber":"150483782", "organizationId":"8169473", "organizationCOID":"OABC-DEF012345678", }, "statusCode":200, "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 404: description: Organization does not exist body: application/json: example: | { "data":{ "statusCode":"404", "message":"Company does not exist:OABC-DEF012345678", "subStatusCode":"C404_8" } } get: is: [getResponse] description: | ## Search Organizations * Existing organizations can be retrieved via query parameters * If the organizations exist, the service responds with a status code of 200 and includes the result in the body of the response queryParameters: organizationId: description: Organization ID type: string example: OABC-DEF012345678 required: false organizationName: description: Organization Name type: string example: Example, Inc. required: false responses: 200: description: All organizations that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/json: example: | { "data":{ "organizations":[ { "ExternalOrganizationId":"OPQ-A12", "GlobalOrganizationId":"OPQA3683757", "organizationId":"3683757", "organizationName":"Example, Inc.", "url":"http://www.example.com" }, { "ExternalOrganizationId":"OPQ-A23", "GlobalOrganizationId":"OPQA3707939", "organizationId":"3707939", "organizationName":"Megacorp", "url":null } ], "statusCode":200, "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 404: description: No organizations found matching search criteria. body: application/json: example: | { "data":{ "statusCode":"404", "message":"Organization Not Found", "subStatusCode":"C404_1" } } post: is: [postResponse] description: | ## Create organization * On successful creation of organization, the service returns a status code of 200 along with the details of the newly created organization in the body of the response. body: application/x-www-form-urlencoded: formParameters: organizationName: description: 'Organization Name' example: Example, Inc. required: true type: string org_url: description: 'Organization URL' example: www.example.com required: false type: string org_address1: description: 'Address Line 1' example: RR 1 Box 68A required: true type: string org_address2: description: 'Address Line 2' example: 16 Willow Dr required: false type: string org_address3: description: 'Address Line 3' example: Willow Farms required: false type: string org_cityRegion: description: 'City' example: Dunley required: true type: string org_stateProvince: description: 'State or Province' example: PA required: true type: string org_postalCode: description: 'Postal Code' example: 15432 required: true type: string org_countryCode: description: 'Country Code' example: US required: true type: string org_phoneNumber: description: 'Phone Number' example: 12123456789 required: false type: string org_faxNumber: description: 'Fax Number' example: 12129876543 required: false type: string org_dunsNumber: description: 'DUNS Number' example: 150483782 required: false type: string parentCOID: description: 'Global Parent Covisint Organization ID' example: OABC-DEF012345678 required: true type: string responses: 200: description: Organization created successfully. body: application/json: example: | { "data":{ "company":{ "organizationName":"Example, Inc.", "org_url":"www.example.com" "org_address1":"RR 1 Box 68A", "org_address2":"16 Willow Dr", "org_address3":"Willow Farms", "org_cityRegion":"Dunley", "org_stateProvince":"PA", "org_postalCode":"15432", "org_countryCode":"US", "org_phoneNumber":"12123456789", "org_faxNumber":"12129876543", "org_dunsNumber":"150483782", "organizationId":"8169473", "organizationCOID":"OABC-DEF012345678", }, "statusCode":200, "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } /roles: is: [secured] description: Collection endpoint for role resources get: is: [getResponse] description: | ## Search Roles * Existing roles can be retrieved via query parameters. * To retrieve roles, the client sends a GET requests to the Resource endpoint; e.g., /roles. * If the idpUserID is passed as input then the admin grantable roles for that user will be returned. * If the idpUserID were not passed as input then the admin manageable roles will be returned. * If the roles exist, the service responds with a status code of 200 and includes the result in the body of the response. headers: queryParameters: idpUserID: description: The IDP User ID (login ID) of the user. See above description for more information. type: string minLength: 4 maxLength: 80 required: false example: USER0002 responses: 200: description: All services that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/json: example: | { "data":{ "statusCode":"200", "subStatusCode":"", "roles":[ { "roleID":"1", "name":"Super User", "externalRoleID":"SUPER_USERS", "privileges":[ { "privilegeID":"100001", "name":"Super User" } ] }, { "roleID":"2", "name":"Application Admin", "externalRoleID":"APP_ADMIN", "privileges":[ { "privilegeID":"100002", "name":"App Admin" } ] } ] } } 400: description: There was a problem with the client's request # substatus codes are mentioned below: # framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application] /{roleId}: is: [secured] uriParameters: roleId: description: External Role ID type: string maxLength: 255 required: true example: Admin description: A specific role. get: is: [getResponse] description: | ## Get a single role If the role exists, the service responds with a status code of 200 and includes the single role in the body of the response. headers: queryParameters: responses: 200: description: All services that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/json: 400: description: There was a problem with the client's request 404: description: Role not found body: application/json: example: '' /tasks: is: [secured] /userApplicationStatus: is: [secured] put: is: [putResponse] description: | ## Modify user application status * An existing user application grant can be suspended, unsuspended or revoked queryParameters: cuid: description: Covisint Unique ID (CUID) type: string required: true example: "EXAMPLE_ADMIN" body: application/x-www-form-urlencoded: formParameters: externalApplicationID: description: IDP application id. Used for mapping IDP app id with Covisint Cloud Identity Provider example: PEJA51-PORTAL required: true type: string reason: description: Short description of the request example: Unsuspend user application required: true type: string status: description: User application status. required: true type: string example: unsuspend enum: [ suspend, unsuspend, delete ] responses: 200: description: Task performed successfully. body: application/json: example: | { "data": { "statusCode": 200, "subStatusCode": "" } } 400: description: There was a problem with the request. body: application/json: example: | { "data": { "statusCode": "400", "message": "Missing required parameter or input parameter name is not supported by the API", "subStatusCode": "C400_1" } } /moveUser: is: [secured] put: is: [putResponse] description: | ## Move user to different Organization * User getting moved cannot be the last admin in the source organization. User cannot be moved if any of the user grants are suspended in the target organization.User cannot be moved if any of the grants are not available in the target organization. queryParameters: cuid: description: Covisint Unique ID (CUID) type: string required: true example: "EXAMPLE_ADMIN" body: application/x-www-form-urlencoded: formParameters: userId: description: Covisint Unique ID of the user to be moved. example: EXAMPLE_ADMIN required: true type: string targetOrgId: description: Target organization where the user to be moved, this needs to be Global Organization Id. example: OPQA3683757 required: true type: string responses: 200: description: user moved successfully. body: application/json: example: | { "data": { "statusCode": 200, "subStatusCode": "" } } 400: description: There was a problem with the request. body: application/json: example: | { "data": { "statusCode": "400", "message": "Missing required parameter or input parameter name is not supported by the API", "subStatusCode": "C400_1" } "data": { "statusCode": "400", "message": "User cannot be moved as he is the only admin in the source organization.", "subStatusCode": "C400_3" } "data": { "statusCode": "400", "message": "User cannot be moved as there are some grants which are suspended in the target organization.", "subStatusCode": "C400_4" } "data": { "statusCode": "400", "message": "User cannot be moved as there are some grants which aren't available in the target organization.", "subStatusCode": "C400_5" } "data": { "statusCode": "400", "message": "User cannot be moved as missing service codes in the target organization.", "subStatusCode": "C400_6" } } 403: description: There was a problem with the request. body: application/json: example: | { "data": { "statusCode": "403", "message": "User is not authorized to move the user", "subStatusCode": "C403_2" } } /userNameSuggestion: is: [secured] get: is: [getResponse] description: | ## Username suggestion * This service provides username suggestions * If the username is available, the service responds with a status code of 200. * If the username is not available, the service responds with a status code of 403 and returns a list of username suggestions in the body of the response. queryParameters: userName: description: User ID type: string required: true example: TRINITY captchaID: description: CAPTCHA ID type: string required: true example: 11189590 verificationCode: description: CAPTCHA value entered by the user example: 82500 required: true type: string firstName: description: 'First name' example: Mary required: true type: string lastName: description: Last name example: Roe required: true type: string responses: 200: description: User name is available body: application/json: example: | { "data": { "statusCode": "200", "subStatusCode": "" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data": { "statusCode": "400", "message": "Missing required parameter or input parameter name is not supported by the API", "subStatusCode": "C400_1" } } 402: description: CAPTCHA verification failure body: application/json: example: | { "data": { "statusCode": "402", "message": "Invalid CAPTCHA verification code", "subStatusCode": "C402_9" } } 403: description: User name not available; alternate suggestions. body: application/json: example: | { "data": { "statusCode": "403", "subStatusCode": "C403_3", "username": "Ro_TRINITY,TRINITY_Ro,TRINITY_2015,Ma_TRINITY,TRINITY_Ma," } } /changeUserId: is: [secured] put: is: [getResponse] description: | ## Change the user ID of a user * On successful change of the user ID, the service responds with a status code of 200. queryParameters: oldIdpUserID: description: Old Identity Provider User ID example: API-DEV1_ADMIN required: true type: string minLength: 4 maxLength: 80 newIdpUserID: description: New Identity Provider User ID example: API-DEV2_ADMIN required: true type: string minLength: 4 maxLength: 80 responses: 200: description: Successfully changed the user ID body: application/json: example : | { "data":{ "statusCode":200, "subStatusCode":"" } } 423: description: New user ID already exists in the system body: application/json: example : | { "data":{ "statusCode":"423", "message":"New user ID already exists in the system", "subStatusCode":"C423_3" } } /userRequests: is: [secured] post: is: [postResponse] description: | ## Register a user * On successful registration of the user, the service responds with a status code of 200 and includes the user details in the body of the response. body: application/x-www-form-urlencoded: formParameters: address1: description: 'Address line 1' example: RR 1 Box 68A required: false type: string address2: description: 'Address line 2' example: 16 Willow Dr required: false type: string address3: description: 'Address line 3' example: Willow Farms required: false type: string city: description: 'City' example: Dunley required: false type: string country: description: 'Country' example: US required: false type: string emailAddress: description: 'User email address. Primarily used for email notification.' example: mary.roe@example.com required: false type: string faxNumber: description: 'Fax number' example: 65643146177 required: false type: string firstName: description: 'First name' example: Mary required: true type: string fixedQuestion1Answer: description: 'The answer for the first security question selected' example: San Francisco required: true type: string fixedQuestion1Id: description: 'The unique ID of the first security question selected' example: 2 required: true type: number fixedQuestion2Answer: description: 'The answer for the second security question selected' example: Red required: true type: string fixedQuestion2Id: description: 'The unique ID of the second security question selected' example: 5 required: true type: number idpUserID: description: | Identity Provider User ID. Typically this would be the user login name. User will use this ID for authentication with Covisint Cloud Identity Provider. The idpUserID must be 4 to 80 characters, can be alphanumeric and can contain no special characters. example: USER0002 required: true type: string minLength: 4 maxLength: 80 jobTitle: description: Job title example: Vice President required: false type: string languagePreference: description: | Language Preference. Should be in ISO 639-1 Code format. Max of 2 chars (e.g. "KO" - Korean, "EN" - English). Default is "EN" example: EN required: false type: string lastName: description: Last name example: Roe required: true type: string middleName: description: Middle name example: Susan required: false type: string mobileNumber: description: Mobile number example: 13671605385 required: false type: string password: description: Password. Can be in plain text or SSHA1. example: LetMeIn12! required: true type: string phoneNumber: description: Phone number example: 13671605783 required: false type: string postalCode: description: Postal code example: 92000 required: false type: string stateProvince: description: State or Province example: PA required: false type: string status: description: User status example: Pending required: false type: string responses: 200: description: | Upon successful creation, the user object will be returned to the client. Once the user is created, the user's IDPUserID cannot be changed. body: application/json: example: | { "data": { "statusCode": 200, "subStatusCode": "", "user": { "lastName": "Roe", "country": "US", "challengeAnswer": "", "city": "Dunley", "prefix": "", "mobileNumber": "", "jobTitle": "Vice President", "postalCode": "92000", "office": "", "fixedQuestion2Answer": "Red", "emailAddress": "mary.roe@example.com", "challengeQuestion": "", "fixedQuestion1Answer": "San Francisco", "address3": "Willow Farms", "address2": "16 Willow Dr", "address1": "RR 1 Box 68A", "stateProvince": "PA", "idpUserID": "AKGKL12G5", "globalCovisintID": "PUEIL237", "firstName": "Mary", "phoneNumber": "13671605783", "faxNumber": "65643146177", "middleName": "Susan", "fixedQuestion1Id": "2", "fixedQuestion2Id": "5", "status": "Pending" } } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API.", "subStatusCode":"C400_1" } } 423: description: User already exists in the system. body: application/json: example: | { "data":{ "statusCode":"423", "message":"User exist in the system. idpUserID=USER001", "subStatusCode":"C423_3" } } /users: is: [secured] description: Collection endpoint for user resources /{userId}: is: [secured] uriParameters: userId: description: Covisint Unique ID (CUID) type: string required: true example: "EXAMPLE_ADMIN" get: is: [getResponse] description: | ## Retrieve an existing user record * If the user exists, the method responds with a status code of 200 and includes the result in the body of the response. responses: 200: description: User record successfully retrieved body: application/json: example: | { "data":{ "statusCode":200, "subStatusCode":"", "user":{ "firstName":"Mary", "middleName":"Susan", "lastName":"Roe", "prefix":"Dr.", "office":"", "fixedQuestion1Id":"0", "fixedQuestion1Answer":"White", "fixedQuestion2Id":"4", "fixedQuestion2Answer":"Austin", "challengeQuestion":"What is my dog's name?", "challengeAnswer":"Coco", "status":"Active", "address1":"RR 1 Box 68A", "address2":"16 Willow Dr", "address3":"Willow Farms", "city":"Dunley", "stateProvince":"PA", "postalCode":"48075", "country":"US", "phoneNumber":"313-227-9707", "mobileNumber":"313-227-9707", "emailAddress":"user@example.com", "faxNumber":"", "jobTitle":"", "idpUserID":"USER001" } } } 404: description: User record not found body: application/json: example: | { "data":{ "statusCode":"404", "message":"User Not Found", "subStatusCode":"C404_4" } } delete: is: [deleteResponse] description: | ## Delete an existing user record * On successful deletion, all associated resource access for the user will be revoked and the status of the user changed to "DELETED". * Deleted users can no longer be authenticated with Covisint's Cloud Identity Provider nor can the user account be reactivated. responses: 200: description: User record successfully deleted body: application/json: example: | { "data":{ "statusCode":200, "subStatusCode":"", } } 404: description: User record not found body: application/json: example: | { "data":{ "statusCode":"404", "message":"User Not Found", "subStatusCode":"C404_4" } } 423: description: User is deleted or cannot be updated. body: application/json: example: | { "data":{ "statusCode": "423", "message": "User is Deleted, Cannot be updated. IDP User ID: USER001-DELETED", "subStatusCode": "C423_4" } } put: is: [putResponse] description: | ## Update existing user details * On successful updation of user details, the method responds with a status code of 200 and includes the updated user details in the body of the response. body: application/x-www-form-urlencoded: formParameters: idpUserID: description: | Identity Provider User ID. Typically this would be the user login name. User will use this ID for authentication with Covisint Cloud Identity Provider. The idpUserID must be 4 to 80 characters, can be alphanumeric and can contain no special characters. example: USER0002 required: false type: string minLength: 4 maxLength: 80 firstName: description: First name example: Mary required: false type: string middleName: description: Middle name example: Susan required: false type: string lastName: description: Last name example: Roe required: false type: string address1: description: Address line 1 example: RR 1 Box 68A required: false type: string address2: description: Address line 2 example: 16 Willow Dr required: false type: string address3: description: Address line 3 example: Willow Farms required: false type: string city: description: City example: Dunley required: false type: string stateProvince: description: State or Province example: PA required: false type: string country: description: Country. Should be in ISO 3166-1 Alpha-2 code format. Default is "US" example: US required: false type: string postalCode: description: Postal code example: 92000 required: false type: string emailAddress: description: Email address. Primarily used for email notification. example: user@example.com required: false type: string phoneNumber: description: Phone number example: 13671605783 required: false type: string faxNumber: description: Fax number example: 313-227-9890 required: false type: string jobTitle: description: Job title example: Vice President required: false type: string languagePreference: description: | Language Preference. Should be in ISO 639-1 Code format. Max of 2 chars (e.g. "KO" - Korean, "EN" - English). Default is "EN" example: EN required: false type: string mobileNumber: description: Mobile number example: 13671605385 required: false type: string password: description: Password. Can be in plain text or SSHA1. example: LetMeIn12! required: false type: string fixedQuestion1Id: description: 'The unique ID of the first security question selected' example: 2 required: false type: number fixedQuestion1Answer: description: 'The answer for the first security question selected' example: San Francisco required: false type: string fixedQuestion2Id: description: 'The unique ID of the second security question selected' example: 5 required: false type: number fixedQuestion2Answer: description: 'The answer for the second security question selected' example: Red required: false type: string status: description: User Status example: Active required: false type: string responses: 200: description: User updated successfully. body: application/json: example: | { "data":{ "statusCode":"200", "subStatusCode":"", "user":{ "idpUserID":"USER0002", "firstName":"Mary", "lastName":"Roe", "password":"gImsixUH6kU5RsR4zwI9lUVX6BMfW9j53gd", "emailAddress":"mary.roe@example.com" } } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API.", "subStatusCode":"C400_1" } } /applications: is: [secured] get: is: [getResponse] description: | ## Search User Applications * Existing user applications can be retrieved via query parameters. * If the applications exist, the service responds with a status code of 200 and includes the result in the body of the response. responses: 200: description: All applications that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/json: example: | { "data":{ "applications":[ { "applicationID":"APP00123", "description":[ { "lang":"en-US", "text":null } ], "externalApplicationID":"", "iconID":"", "name":[ { "lang":"en-US", "text":null } ], "url":"" }, { "applicationID":"APP000234", "description":[ { "lang":"en-US", "text":"Sample Portal" } ], "externalApplicationID":"", "iconID":"", "name":[ { "lang":"en-US", "text":"Sample Portal" } ], "url":"https://sample.portal.covisint.com" } ], "statusCode":200, "subStatusCode":"" } } 404: description: User does not exist body: application/json: example: | { "data":{ "statusCode":"404", "message":"User Not Found", "subStatusCode":"C404_4" } } 423: description: User is suspended or deleted. Application cannot be retrieved body: application/json: post: is: [postResponse] description: | ## Add Application to User * If the user exists, the service responds with a status code of 200 and includes the result in the body of the response. body: application/x-www-form-urlencoded: formParameters: packageId: description: Package ID example: 99103000 required: true type: number responses: 200: description: User application successfully added body: application/json: example: | { "data":{ "statusCode":200, "subStatusCode":"" } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 500: description: 'Application is already granted or requested, or the user to be granted does not exist' body: application/json: example: | { "data":{ "statusCode":"500", "message":"Application is already granted or requested.", "subStatusCode":"C500_1" } } /roles: is: [secured] /{roleId}: is: [secured] uriParameters: roleId: description: Role ID type: integer required: true example: 611 delete: is: [deleteResponse] description: | ## Delete role from user * If the userId and role exist, the service responds with a status code of 200. responses: 200: description: Role removed from user successfully body: application/json: example: | { "data":{ "statusCode":200, "subStatusCode":"" } } 404: description: User or role not found body: application/json: example: | { "data":{ "statusCode":"404", "message":"User[ Or Role] Not Found", "subStatusCode":"C404_4" } } get: is: [getResponse] description: | ## Search User Roles * Existing user roles can be retrieved via query parameters * If the roles exist, the service responds with a status code of 200 and includes the result in the body of the response. responses: 200: description: All user roles that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/json: example: | { "data":{ "roles":[ { "name":"Exchange Operator", "privileges":[ { "name":"Approve New Organization", "privilegeID":"501" }, { "name":"Approve User", "privilegeID":"502" } ], "externalRoleID":"", "roleID":"609" } ], "statusCode":200, "subStatusCode":"" } } 404: description: User does not exist body: application/json: example: | { "data":{ "statusCode":"404", "message":"User Not Found", "subStatusCode":"C404_4" } } post: is: [postResponse] description: | ## Add roles to user * An existing role can be added to a user by providing the role ID as a query parameter. * If the user and role exist, the service responds with a status code of 200 and includes the result in the body of the response. queryParameters: roleId: description: Role ID example: 605 required: true type: integer responses: 200: description: Role assigned to user successfully body: application/json: example: | { "data":{ "statusCode":200, "subStatusCode":"" } } 404: description: User or role does not exist body: application/json: example: | { "data":{ "statusCode":"404", "message":"User[ Or Role] Not Found", "subStatusCode":"C404_4" } } /password: is: [secured] description: Update Password put: is: [putResponse] description: | ## Update Password --- Update a user's password. The verification scheme is set as a request parameter. There are three supported verification schemes: * __verificationScheme=token__: The requestor's credentials dictate whether the operation is allowed. The old password is required only if the requestor is the same as the subject. If they are different then the requestor requires the proper privilege to update the subject's password. * __verificationScheme=securityQuestions__: Answers to security questions are checked as verification. If this verification scheme is used then a random password is assigned and returned if the correct security answers are sent in the request. * __verificationScheme=password__: The existing password is checked as verification. queryParameters: verificationScheme: description: | Verification scheme to be used. If "token" then the requestor's credentials are used to verify the request. If "securityQuestions" then the security answers are used to verify the request. example: token required: true type: string enum: [ password, securityQuestions, token ] headers: Authorization: description: | Access token that is obtained from the /token endpoint of the oauth API. Required when *verificationScheme* is *token* and optional when *verificationScheme* is *securityQuestions* or *password*. pattern: ^Bearer .*$ example: Bearer ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk required: false client_id: description: Client ID. Required when *verificationScheme* is *securityQuestions* or *password* and Access not provided. example: YWb4hgyU657d2YPA9hipc9HUeXR6faGB type: string body: application/x-www-form-urlencoded: formParameters: oldPassword: description: When verificationScheme is "token" or "password", current password. This parameter is required if the requestor and subject are the same. example: MyOldP@ssword1 required: false type: string newPassword: description: When verificationScheme is "token" or "password", the new password. example: MyNewP@ssword1 required: false type: string maxLength: 20 expireNewPassword: description: | When verificationScheme is "token", indicate whether to expire the new password. If the requestor and subject are the same, this parameter is ignored and the new password is not expired. example: true required: false type: boolean fixedQuestion1Id: description: When verificationScheme is "securityQuestions", the ID of the first security question. example: 2 fixedQuestion1Answer: description: When verificationScheme is "securityQuestions", the answer to the first security question. example: San Francisco fixedQuestion2Id: description: When verificationScheme is "securityQuestions", the ID of the first security question. example: 5 fixedQuestion2Answer: description: When verificationScheme is "securityQuestions", the answer to the first security question. example: Red responses: 200: description: When verificationScheme is "token" or "password", a success message will be returned. When verificationScheme is "securityQuestions", the username and a temporary password will be returned. body: application/json: example: | With verificationScheme = "token" or "password": { "data":{ "statusCode":"200", "message":"Password Successfully Changed", "subStatusCode":"" } } With verificationScheme = "securityQuestions": { "data":{ "tempPassword":"!#$NT$s6", "statusCode":"200", "subStatusCode":"", "username":"TJBBFCAG" } } 402: description: | There was a problem with the client's request ___ Substatus codes and error messages are mentioned below: + C402_4 - Invalid answer to challenge question + C402_7 - Current password is invalid + C402_8 - Password did not meet policy body: application/json: example: | With verificationScheme = "token": { "data":{ "statusCode":"402", "message":"Password did not comply with the policy.", "subStatusCode":"C402_8" } } With verificationScheme = "securityQuestions": { "data":{ "statusCode":"402", "message":"Invalid challenge response", "subStatusCode":"C402_4" } } 423: description: | User is suspended or deleted. ___ Substatus codes and error messages are mentioned below: + C423_2 - Account suspended or deleted /securityQuestions: get: is: [getResponse] description: | ## Get User Security Questions * On a successful request, the service responds with a status code of 200 and includes the result in the body of the response. headers: Authorization: description: Access token that is obtained from /token endpoint of OAuth API. This parameter is required when client_id is not provided. pattern: ^Bearer .*$ example: Bearer 1249eBBBe0eEER88FFdd required: false client_id: description: Client ID is required only when access token is not provided. example: YWb4hgyU657d2YPA9hipc9HUeXR6faGB type: string required: false responses: 200: description: All user security questions were successfully retrieved. body: application/json: example: | { "data":{ "fixedQuestion1Id":"2", "statusCode":"402", "subStatusCode":"C402_2", "username":"DYV17L25", "fixedQuestion2Id":"5" } } 401: description: Invalid client_id body: application/json: example: | When client_id is invalid { "status": 401, "apiMessage": "Invalid Client-Id.", "apiStatusCode": "gateway:client-id:invalid" } 404: description: User does not exist body: application/json: example: | { "data":{ "statusCode":"404", "message":"User Not Found", "subStatusCode":"C404_4" } } 423: description: User account is suspended or deleted body: application/json: example: | { "data":{ "statusCode":"423", "message":"Account suspended or deleted, user not allowed to change", "subStatusCode":"C423_2" } } get: is: [getResponse] description: | ## Search Users * Existing users can be retrieved using query parameters like firstName, lastName, emailId, etc. * If the query parameters match any existing users, the service responds with a status code of 200 and includes the result in the body of the response. * At least one query parameter must be provided to get any results. queryParameters: firstName: description: 'First name' example: Mary required: false type: string middleName: description: Middle name example: Susan required: false type: string lastName: description: Last name example: Roe required: false type: string address1: description: 'Address line 1' example: RR 1 Box 68A required: false type: string address2: description: 'Address line 2' example: 16 Willow Dr required: false type: string address3: description: 'Address line 3' example: Willow Farms required: false type: string city: description: City example: Dunley required: false type: string stateProvince: description: State or Province example: PA required: false type: string country: description: 'Country' example: US required: false type: string emailAddress: description: 'User email address. Primarily used for email notification.' example: mary.roe@example.com required: false type: string phoneNumber: description: Phone number example: 13671605783 required: false type: string mobileNumber: description: Mobile number example: 13671605385 required: false type: string jobTitle: description: Job title example: Vice President required: false type: string fixedQuestion1Id: description: 'The unique ID of the first security question selected' example: 2 required: false type: number fixedQuestion1Answer: description: 'The answer for the first security question selected' example: San Francisco required: false type: string fixedQuestion2Id: description: 'The unique ID of the second security question selected' example: 5 required: false type: number fixedQuestion2Answer: description: 'The answer for the second security question selected' example: Red required: false type: string challengeQuestion: description: Challenge question example: "What is my dog's name" required: false type: string challengeAnswer: description: 'Challenge answer' example: Coco required: false type: string idpUserID: description: | Identity Provider User ID. Typically this would be the user login name. User will use this ID for authentication with Covisint Cloud Identity Provider. The idpUserID must be 4 to 80 characters, can be alphanumeric and can contain no special characters. example: USER0002 required: false type: string minLength: 4 maxLength: 80 responses: 200: description: All users that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/json: example: | { "data":{ "statusCode":200, "subStatusCode":"", "users":[ { "firstName":"Mary", "middleName":"Susan", "lastName":"Roe", "prefix":"Dr.", "office":"", "fixedQuestion1Id":"0", "fixedQuestion1Answer":"White", "fixedQuestion2Id":"4", "fixedQuestion2Answer":"Austin", "challengeQuestion":"What is my dog's name?", "challengeAnswer":"Coco", "status":"Active", "address1":"RR 1 Box 68A", "address2":"16 Willow Dr", "address3":"Willow Farms", "city":"Dunley", "stateProvince":"PA", "postalCode":"48075", "country":"US", "phoneNumber":"313-227-9707", "mobileNumber":"313-227-9707", "emailAddress":"user@example.com", "faxNumber":"", "jobTitle":"", "idpUserID":"USER001" } ] } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API", "subStatusCode":"C400_1" } } 404: description: No user records found matching specified criteria body: application/json: example: | { "data":{ "statusCode":"404", "message":"User Not Found", "subStatusCode":"C404_4" } } post: is: [postResponse] description: | ## Create user * On successful creation of the user, the service responds with a status code of 200 and includes the details of the newly created user in the body of the response. body: application/x-www-form-urlencoded: formParameters: address1: description: Address line 1 example: RR 1 Box 68A required: false type: string address2: description: Address line 2 example: 16 Willow Dr required: false type: string address3: description: Address line 3 example: Willow Farms required: false type: string city: description: City example: Dunley required: false type: string country: description: Country. Should be in ISO 3166-1 Alpha-2 code format. Default is "US" example: US required: false type: string emailAddress: description: Email address. Primarily used for email notification. example: user@example.com required: false type: string faxNumber: description: Fax number example: 313-227-9890 required: false type: string firstName: description: First name example: Mary required: true type: string fixedQuestion1Answer: description: 'The answer for the first security question selected' example: San Francisco required: true type: string fixedQuestion1Id: description: 'The unique ID of the first security question selected' example: 2 required: true type: number fixedQuestion2Answer: description: 'The answer for the second security question selected' example: Red required: true type: string fixedQuestion2Id: description: 'The unique ID of the second security question selected' example: 5 required: true type: number idpUserID: description: | Identity Provider User ID. Typically this would be the user login name. User will use this ID for authentication with Covisint Cloud Identity Provider. The idpUserID must be 4 to 80 characters, can be alphanumeric and can contain no special characters. example: USER0002 required: true type: string minLength: 4 maxLength: 80 jobTitle: description: Job title example: Vice President required: false type: string languagePreference: description: | Language Preference. Should be in ISO 639-1 Code format. Max of 2 chars (e.g. "KO" - Korean, "EN" - English). Default is "EN" example: EN required: false type: string lastName: description: Last name example: Roe required: true type: string middleName: description: Middle name example: Susan required: false type: string mobileNumber: description: Mobile number example: 13671605385 required: false type: string password: description: Password. Can be in plain text or SSHA1. example: LetMeIn12! required: true type: string phoneNumber: description: Phone number example: 13671605783 required: false type: string postalCode: description: Postal code example: 92000 required: false type: string stateProvince: description: State or Province example: PA required: false type: string status: description: User Status example: Active required: false type: string responses: 200: description: User created successfully. body: application/json: example: | { "data":{ "statusCode":"200", "subStatusCode":"", "user":{ "idpUserID":"USER0002", "firstName":"Mary", "lastName":"Roe", "password":"gImsixUH6kU5RsR4zwI9lUVX6BMfW9j53gd", "emailAddress":"mary.roe@example.com" } } } 400: description: "There was a problem with the client's request" body: application/json: example: | { "data":{ "statusCode":"400", "message":"Missing required parameter or input parameter name is not supported by the API.", "subStatusCode":"C400_1" } } 423: description: User already exists in the system. body: application/json: example: | { "data":{ "statusCode":"423", "message":"User exist in the system. idpUserID=USER0002", "subStatusCode":"C423_3" } }