#%RAML 0.8 title: IDM API baseUri: https://api.us1.covisint.com/idm/v2 protocols: - HTTPS schemas: - errorResponseSchema: "{\n \"id\" : \"http://api.covisint.com/schema/errorResponseSchema\",\n \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\" : \"object\",\n \ \"description\" : \"Representation of an HTTP 4xx/5xx error response.\",\n \"properties\" : {\n \"status\" : { \n \"type\" : \"number\",\n \"minimum\" : 400,\n \ \"maximum\" : 599,\n \"description\" : \"The HTTP status code.\",\n \ \"required\": true\n },\n \"apiMessage\" : { \n \"type\" : \"string\",\n \ \"description\" : \"A helpful, human-readable description of the error, useful for basic diagnostics.\" \n },\n \"apiStatusCode\" : {\n \"type\" : \"string\",\n \"description\" : \"The API-specific status code.\"\n }\n\n \ }\n}\n" 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: 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: 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: &2 description: The URI requested is invalid or the resource requested does not exist. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: &1 description: An unknown server error occurred body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema - postResponse: responses: 500: *1 - deleteResponse: responses: 404: *2 500: *1 - putResponse: responses: 404: *2 500: *1 "/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 \n--- \n#### Send Email Invitation\n* The *template* query parameter is set to *invitation*.\n* The type of invite sent depends on the *inviteType* form parameter.\n * If *inviteType=1* (Company), the parent *companyId* form parameter is not required.\n * For other *inviteType* values, the *companyId* form parameter is required.\n* The *to* form parameter is mandatory.\n\n#### Send Forgot Login ID Email \n* The *template* query parameter is set to *forgotUserIdByEmail*.\n* Authorization is not required\n* The *client_id* header is mandatory for this form.\n* The *emailAddress* query parameter is also mandatory.\n* The *companyId*, *inviteType* and *to* form parameters are not required.\n" 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 "/{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: '' "/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 \n{\n \"status\": 401,\n \"apiMessage\": \"Invalid Client-Id.\",\n \"apiStatusCode\": \"gateway:client-id:invalid\"\n}\n" 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" } } "/tasks/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" } } "/tasks/userNameSuggestion": is: - secured get: is: - getResponse description: "## Username suggestion\n* This service provides username suggestions \ \n* If the username is available, the service responds with a status code of 200. \n* If the username is not available, the service responds with a status code of 403\n and returns a list of username suggestions in the body of the response.\n" 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," } } "/tasks/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" } }