{"openapi":"3.0.3","info":{"title":"AaaS User Onboarding API - STANDARD","version":"1.1","description":"Learn more: <a href=\"https://amerisourcebergen.sharepoint.com/:u:/s/SAPCDCTechForum/IQA0aJayfJoGQ4AxUWGoOj_WAamrA4uCJUfWX5GHjoX8_1E?e=deMkxQ\" target=\"_blank\">AaaS User Onboarding API — Developer Primer</a>\n\n<hr>\n\nThis API performs CRUD operations for AaaS users:\n  - The <i>Standard API</i> provides essential operations for the vast majority of application integrations. Only use <i>Standard API</i> unless the CIAM AaaS Team provided guidance to use the <i>Extended API</i>.\n  - The <i>Extended API</i> is for exceptional cases where application-specific attributes are maintained in AaaS. If you think your application requires this, consult with the CIAM AaaS Team.\n\nTo use the API in this studio:\n  - Retrieve API <code>access_token</code> via /GenerateToken API (using this studio or Postman)\n  - Configure the <code>access_token</code> as the Authorize bearer token\n  - Once the Authorize bearer token is set, you can execute the /user endpoints\n\nTo test an endpoint:\n  - Click \"Try it Out\" to set the configuration\n  - After configuring all endpoint parameters, click \"Execute\" to see the results\n\n<hr>\n\nHow to interpret API responses\n<br/>This API simplifies user onboarding between your application and AaaS by abstracting CRUD operations through an API manager (APIM). When your application makes an API request, the APIM validates it and then executes the operation on the backend CIAM. The response is a JSON payload containing information from both the APIM and CIAM.\n\n```json\n{\n  apim: { /* APIM details */ },\n  ciam: { /* CIAM details */ }\n}\n```\n<code>ciam.errorCode</code> indicates the overall disposition of an operation; use it to determine exception handling in your application logic.  <code>apim.errorCode</code> is a convenience for correcting \"pre-flight\" issues indicated by non-zero <code>ciam.errorCode</code> to \\\"Fix errors in your request\\.\"  This design helps clarify where errors occur to assist with triage and troubleshooting."},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/ROBERTBURGESS_1/Implicit/1.0.0"},{"description":"APIM DEV","url":"https://abapimdev.amerisourcebergen.com"},{"description":"APIM STAGE","url":"https://abapimstg.amerisourcebergen.com"},{"description":"APIM PROD","url":"https://abapim.amerisourcebergen.com"}],"tags":[{"name":"/GenerateToken (API Bearer Token)"},{"name":"/user API"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"APIM access token obtained from /v1/OAuthService/GenerateToken"}},"parameters":{"AaaS_app_id":{"name":"AaaS_app_id","in":"header","required":true,"schema":{"type":"string"},"description":"AaaS application identifier (app_id)."},"UID":{"name":"UID","in":"query","required":false,"schema":{"type":"string"},"description":"AaaS account UID (automatically generated via PUT /user)."},"email":{"name":"email","in":"query","required":false,"schema":{"type":"string","format":"email"},"description":"User email address (<b>best practice: URL encode</b> to encapsulate special characters)"},"appUID":{"name":"app.UID","in":"query","required":false,"schema":{"type":"string"},"description":"Application-specific UID (note the dot-notation in the parameter name)."}},"schemas":{"TokenResponse":{"type":"object","properties":{"refresh_token_expires_in":{"type":"string","example":"0"},"api_product_list":{"type":"string","example":"[Delivery, CIAM]"},"api_product_list_json":{"type":"array","items":{"type":"string"},"example":["Delivery","CIAM"]},"organization_name":{"type":"string","example":"ab-cloud-foundry-dev"},"developer.email":{"type":"string","format":"email"},"token_type":{"type":"string","example":"BearerToken"},"issued_at":{"type":"string"},"client_id":{"type":"string"},"access_token":{"type":"string"},"application_name":{"type":"string"},"scope":{"type":"string","example":""},"expires_in":{"type":"string","example":"14399"},"refresh_count":{"type":"string","example":"0"},"status":{"type":"string","example":"approved"}}},"OAuthErrorResponse_grant_type":{"type":"object","properties":{"ErrorCode":{"type":"string","example":"invalid_request"},"Error":{"type":"string","example":"Required param : grant_type"}}},"oauth_token__invalid_client_id":{"type":"object","properties":{"ErrorCode":{"type":"string","example":"invalid_client"},"Error":{"type":"string","example":"Client identifier is required"}}},"ApimEnvelope_schema__BASIC":{"type":"object","properties":{"apiVersion":{"type":"integer","example":1},"op":{"type":"object","properties":{"endpoint":{"type":"string","example":"GET /user"},"params":{"description":"Array of params","type":"array","items":{"type":"string"}},"time":{"type":"string","format":"date-time"}}}}},"ApimEnvelope_schema__BASIC_ERROR":{"type":"object","properties":{"errorCode":{"type":"integer","nullable":true},"statusCode":{"nullable":true,"oneOf":[{"type":"integer"},{"type":"string"}]},"errorMessage":{"type":"string","nullable":true},"errorDetails":{"nullable":true,"type":"array","items":{"type":"string","example":"<array of strings>"}}}},"ApimEnvelope_payload__SUCCESS":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_schema__BASIC"}]},"ApimEnvelope_payload__ERROR":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_schema__BASIC"},{"$ref":"#/components/schemas/ApimEnvelope_schema__BASIC_ERROR"}]},"ApimEnvelope_payload__GET_user":{"allOf":[{"type":"object","properties":{"op":{"type":"object","properties":{"endpoint":{"type":"string","example":"GET /user"},"params":{"type":"array","items":{"type":"string"},"example":["UID"]}}}}}]},"ApimEnvelope_payload__PUT_user":{"allOf":[{"type":"object","properties":{"op":{"type":"object","properties":{"endpoint":{"type":"string","example":"PUT /user"},"params":{"type":"array","items":{"type":"string"},"example":["profile","app"]}}}}}]},"ApimEnvelope_payload__PATCH_user":{"allOf":[{"type":"object","properties":{"op":{"type":"object","properties":{"endpoint":{"type":"string","example":"PATCH /user"},"params":{"type":"array","items":{"type":"string"},"example":["UID","app"]}}}}}]},"ApimEnvelope_payload__DELETE_user":{"allOf":[{"type":"object","properties":{"op":{"type":"object","properties":{"endpoint":{"type":"string","example":"DELETE /user"},"params":{"type":"array","items":{"type":"string"},"example":["email"]}}}}}]},"CiamEnvelope_schema__BASIC":{"type":"object","properties":{"callId":{"type":"string"},"errorCode":{"type":"integer","nullable":false},"apiVersion":{"type":"integer","example":2,"nullable":false},"statusCode":{"type":"integer","nullable":false},"time":{"type":"string","format":"date-time"}}},"CiamEnvelope_schema__BASIC_ERROR":{"type":"object","properties":{"statusReason":{"type":"string"},"errorMessage":{"type":"string","nullable":true},"errorDetails":{"nullable":true,"type":"array","items":{"type":"string"}}}},"CiamEnvelope_schema__when_APIM_ERROR":{"type":"object","properties":{"errorCode":{"type":"number"},"errorMessage":{"type":"string","nullable":true},"errorDetails":{"nullable":true,"type":"array","items":{"type":"string"}}}},"CiamEnvelope_payload__SUCCESS":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_schema__BASIC"}]},"CiamEnvelope_payload__ERROR":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_schema__BASIC"},{"$ref":"#/components/schemas/CiamEnvelope_schema__BASIC_ERROR"}]},"CiamEnvelope_payload__when_APIM_ERROR":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_schema__when_APIM_ERROR"}]},"CiamEnvelope_payload__UID_Only":{"type":"object","properties":{"UID":{"type":"string"}}},"CiamEnvelope_payload__User_Record_BASIC":{"allOf":[{"type":"object","properties":{"statusCode":{"type":"integer","example":200},"results":{"nullable":true,"type":"array","items":{"type":"object","properties":{"UID":{"type":"string"},"profile":{"type":"object","properties":{"lastName":{"type":"string"},"firstName":{"type":"string"},"email":{"type":"string"}}}}}},"objectsCount":{"type":"integer","example":1},"totalCount":{"type":"integer","example":1}}}]},"CiamEnvelope_payload__User_Record_EXTENDED":{"allOf":[{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"app":{"type":"object","properties":{"<app-specific keys>":{"type":"string","example":"<key-pair values>"}}}}}}}}]},"GET_user_200":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__GET_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/CiamEnvelope_payload__User_Record_BASIC"}]}}},"GET_user_200__EXTENDED":{"allOf":[{"$ref":"#/components/schemas/GET_user_200"},{"type":"object","properties":{"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__User_Record_EXTENDED"}]}}}]},"GET_user_400":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__ERROR"},{"type":"object","properties":{"errorCode":{"example":401000},"statusCode":{"example":400}}}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__when_APIM_ERROR"},{"type":"object","properties":{"errorCode":{"example":401000},"errorMessage":{"example":"Fix errors in your request"},"errorDetails":{"example":"Pre-flight failed for this request"}}}]}}},"PUT_user_200":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__PUT_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/CiamEnvelope_payload__UID_Only"}]}}},"PUT_user_400":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__ERROR"},{"$ref":"#/components/schemas/ApimEnvelope_payload__PUT_user"},{"type":"object","properties":{"errorCode":{"example":400006},"statusCode":{"example":400}}}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__when_APIM_ERROR"},{"type":"object","properties":{"errorCode":{"example":400006},"errorMessage":{"example":"Fix errors in your request"},"errorDetails":{"example":"Pre-flight failed for this request"}}}]}}},"PUT_user_403":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__PUT_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__ERROR"},{"type":"object","properties":{"errorCode":{"example":403023},"statusCode":{"example":403},"statusReason":{"example":"Forbidden"},"errorMessage":{"example":"No user permission"},"errorDetails":{"example":["You do not have permission to set field \"<CIAM schema element>\""]}}}]}}},"PUT_user_409":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__PUT_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__ERROR"},{"$ref":"#/components/schemas/CiamEnvelope_payload__User_Record_BASIC"},{"type":"object","properties":{"errorCode":{"example":200010},"statusCode":{"example":409}}}]}}},"PUT_user_409__EXTENDED":{"allOf":[{"$ref":"#/components/schemas/PUT_user_409"},{"type":"object","properties":{"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__User_Record_EXTENDED"}]}}}]},"PATCH_user_200":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__PATCH_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__SUCCESS"}]}}},"PATCH_user_400":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__ERROR"},{"$ref":"#/components/schemas/ApimEnvelope_payload__PATCH_user"},{"type":"object","properties":{"errorCode":{"example":400006},"statusCode":{"example":400}}}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__when_APIM_ERROR"},{"type":"object","properties":{"errorCode":{"example":400006},"errorMessage":{"example":"Fix errors in your request"},"errorDetails":{"example":"Pre-flight failed for this request"}}}]}}},"PATCH_user_403":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__PATCH_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__ERROR"},{"type":"object","properties":{"errorCode":{"example":403005},"statusCode":{"example":403}}}]}}},"DELETE_user_200":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__DELETE_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__SUCCESS"}]}}},"DELETE_user_400":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__ERROR"},{"$ref":"#/components/schemas/ApimEnvelope_payload__DELETE_user"},{"type":"object","properties":{"errorCode":{"example":401000},"statusCode":{"example":400}}}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__when_APIM_ERROR"},{"type":"object","properties":{"errorCode":{"example":401000},"errorMessage":{"example":"Fix errors in your request"},"errorDetails":{"example":"Pre-flight failed for this request"}}}]}}},"DELETE_user_403":{"type":"object","additionalProperties":false,"properties":{"apim":{"allOf":[{"$ref":"#/components/schemas/ApimEnvelope_payload__SUCCESS"},{"$ref":"#/components/schemas/ApimEnvelope_payload__DELETE_user"}]},"ciam":{"allOf":[{"$ref":"#/components/schemas/CiamEnvelope_payload__ERROR"},{"type":"object","properties":{"errorCode":{"example":403005},"statusCode":{"example":403}}}]}}},"PUT_sample_request_body_BASIC":{"type":"object","required":["profile"],"properties":{"profile":{"type":"object","required":["email","firstName","lastName"],"properties":{"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"}}}}},"PUT_sample_request_body_EXTENDED":{"allOf":[{"$ref":"#/components/schemas/PUT_sample_request_body_BASIC"},{"type":"object","properties":{"app":{"type":"object","properties":{"<app-specific keys>":{"type":"string","example":"<key-pair values> (consult with AaaS team)"}}}}}]},"PATCH_sample_request_body_BASIC":{"type":"object","required":["UID","app"],"properties":{"UID":{"type":"string"},"app":{"type":"object","properties":{"<app-specific keys>":{"type":"string","example":"<key-pair values> (consult with AaaS team)"}}}}}},"responses":{"oauth_token__invalid_grant_type":{"description":"Bad Request (missing or bad param: <code>grant_type</code>)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse_grant_type"}}}},"oauth_token__invalid_client_id":{"description":"Unauthorized (missing or bad param: <code>client_id</code> or <code>client_secret</code>)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/oauth_token__invalid_client_id"}}}},"GET_user_200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GET_user_200"}}}},"GET_user_200__EXTENDED":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GET_user_200__EXTENDED"}}}},"GET_user_400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GET_user_400"}}}},"PUT_user_200":{"description":"OK; User onboarded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PUT_user_200"}}}},"PUT_user_400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PUT_user_400"}}}},"PUT_user_403":{"description":"User exists, the request body is valid structure, but a targeted AaaS schema field is not writable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PUT_user_403"}}}},"PUT_user_409":{"description":"Conflict error but result is OK because login identifier already exists; response contains user details.<br/>Note: HTTP status is 409 but <code>errorCode</code> is 200-level, indicating acceptable result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PUT_user_409"}}}},"PUT_user_409__EXTENDED":{"description":"Conflict error but result is OK because login identifier already exists; response contains user details.<br/>Note: HTTP status is 409 but <code>errorCode</code> is 200-level, indicating acceptable result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PUT_user_409__EXTENDED"}}}},"PATCH_user_200":{"description":"OK; User updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PATCH_user_200"}}}},"PATCH_user_400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PATCH_user_400"}}}},"PATCH_user_403":{"description":"Unauthorized/unknown user or schema access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PATCH_user_403"}}}},"DELETE_user_200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DELETE_user_200"}}}},"DELETE_user_400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DELETE_user_400"}}}},"DELETE_user_403":{"description":"Unauthorized/unknown user or schema access error <!-- EXTENDED <br/>Contact the CIAM AaaS Team for assistance with schema access errors. -->","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DELETE_user_403"}}}}}},"paths":{"/v1/OAuthService/GenerateToken":{"post":{"tags":["/GenerateToken (API Bearer Token)"],"summary":"Generate APIM access token","description":"Client credentials token generation (application/x-www-form-urlencoded). <p><b>Oauth client ID and secret are provided by CIAM team or APIM team.</b>","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string"}}}}}},"responses":{"200":{"description":"OK (token generated)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"$ref":"#/components/responses/oauth_token__invalid_grant_type"},"401":{"$ref":"#/components/responses/oauth_token__invalid_client_id"}}}},"/api/ciam/aaas/v1/user":{"get":{"tags":["/user API"],"summary":"Retrieve user(s)","description":"<!-- STANDARD version\n-->\nReturns a user based on either <code>UID</code> (primary) or <code>email</code> (secondary)\n\n<!-- EXTENDED verion:\nReturns a list of user(s) based on search criteria.\nAt least one of these parameters is required: <code>UID</code>, <code>email</code>, <code>app.UID</code>\n<p>Search by <code>UID</code> or <code>email</code> returns a single user because these are unique identifiers.  Search by <code>app.UID</code> can return more than one user if the same value is assigned to multiple users (e.g., multiple users assigned to a single application account).\n<p>This is the order of precedence for these prameters:\n  <ul>\n    <li><code>UID</code> takes precedence, and other parameters are ignored.</li>\n    <li>Otherwise, <code>email</code> takes precedence, and other parameters are ignored.</li>\n    <li>Otherwise, <code>app.UID</code> is the last resort.</li>\n  </ul>\n  -->","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AaaS_app_id"},{"$ref":"#/components/parameters/UID"},{"$ref":"#/components/parameters/email"}],"responses":{"200":{"$ref":"#/components/responses/GET_user_200"},"400":{"$ref":"#/components/responses/GET_user_400"}}},"put":{"tags":["/user API"],"summary":"Create user (or report existing)","description":"Create a user with profile fields.  The request body is a JSON structure containing the core user details with <code>email</code> becoming the login identity.\n<br> Note: if AaaS user already exists, HTTP 409 occurs due to the conflict, but <code>errorCode</code> indicates success and user details are returned in the response.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AaaS_app_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PUT_sample_request_body_BASIC"}}}},"responses":{"200":{"$ref":"#/components/responses/PUT_user_200"},"400":{"$ref":"#/components/responses/PUT_user_400"},"403":{"$ref":"#/components/responses/PUT_user_403"},"409":{"$ref":"#/components/responses/PUT_user_409"}}},"delete":{"tags":["/user API"],"summary":"Delete user","description":"Delete application-specific user data based on either <code>UID</code> (primary) or <code>email</code> (secondary)\n<p>\nAaaS is an SSO service, so <b>the AaaS user record is preserved</b> as a valid login identity for other applications to which the user may have access.  This API should be called when the user is being off-boarded from your application in order to clean up any app-specific data.  Response <code>errorCode</code> 403023 should be treated as a successful response unless you are implementing the <i>Extended API</i>.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AaaS_app_id"},{"$ref":"#/components/parameters/UID"},{"$ref":"#/components/parameters/email"}],"responses":{"200":{"$ref":"#/components/responses/DELETE_user_200"},"400":{"$ref":"#/components/responses/DELETE_user_400"},"403":{"$ref":"#/components/responses/DELETE_user_403"}}}}}}