Automated commit 'Merge pull request #1388 from sailpoint/amalta/PLTIN-5269

PLTIN-5269: Moved docs for GET and PATCH operations to V3' by github action: 6018519847
2025-12-09 20:37:50 +00:00 · 2023-08-29 23:16:51 +00:00
parent 54648c1c93
commit d02498ff0f
4 changed files with 190 additions and 110 deletions
--- a/idn/beta/paths/auth-user.yaml
+++ b/idn/beta/paths/auth-user.yaml
@@ -1,12 +1,11 @@
-get:
-  operationId: getAuthUser
+put:
+  operationId: setAuthUser
  tags:
    - Auth User
-  summary: Auth User Details
-  description: >-
-    This API returns the specified user's authentication system details.
-
-    Requires security scope of:  'sp:auth-user:read'
+  summary: Auth User Update - Overwrite
+  description: Update an existing user in the authentication system by over overwriting the information with new information.
+  security:
+    - oauth2: [sp:auth-user-internal:update]
  parameters:
    - in: path
      name: id
@@ -16,106 +15,6 @@ get:
      schema:
        type: string
      example: ef38f94347e94562b5bb8424a56397d8
-#  security:
-#    - oauth2: [sp:auth-user:read]
-  responses:
-    '200':
-      description: The specified user's authentication system details.
-      content:
-        application/json:
-          schema:
-            $ref: '../schemas/AuthUser.yaml'
-    '400':
-      $ref: '../../v3/responses/400.yaml'
-    '401':
-      $ref: '../../v3/responses/401.yaml'
-    '403':
-      $ref: '../../v3/responses/403.yaml'
-    '404':
-      $ref: '../../v3/responses/404.yaml'
-    '429':
-      $ref: '../../v3/responses/429.yaml'
-    '500':
-      $ref: '../../v3/responses/500.yaml'
-
-patch:
-  operationId: patchAuthUser
-  tags:
-    - Auth User
-  summary: Auth User Update - PATCH
-  description: Update an existing user in the authentication system with a PATCH request.
-#  security:
-#    - oauth2: [sp:auth-user:update]
-  parameters:
-    - in: path
-      name: id
-      description: >-
-        Identity ID
-      required: true
-      schema:
-        type: string
-  requestBody:
-    required: true
-    description: |
-      A list of auth user update operations according to the [JSON Patch](https://tools.ietf.org/html/rfc6902) standard.
-
-      PATCH can only be applied to the following fields:
-        *   "capabilities"
-
-      A list of valid capabilities can be found using the GET ams/v3/authorization/authorization-capabilities/ endpoint.
-      Capabilities can only be patched if they are administrator assignable, as indicated by the 'adminAssignable' field from the output of list authorization-capabilities.
-      Capabilities that have a legacy group ('legacyGroup' field) need to be patched using the legacyGroup name (e.g. 'ORG_ADMIN').
-      Capabilities that are adminAssignable but do not have a legacyGroup can be patched using the ams id (e.g. 'cam:new-role').
-
-      A 400.1.1 Illegal update attempt detail code indicates that you attempted to PATCH a field that is not allowed.
-
-      Requires security scope of 'sp:auth-user:update'
-    content:
-      application/json-patch+json:
-        schema:
-          type: array
-          items:
-            $ref: '../schemas/JsonPatchOperation.yaml'
-        example:
-            - op: "replace"
-              path: "/capabilities"
-              value: ["ORG_ADMIN"]
-  responses:
-    '200':
-      description: Auth user updated.
-      content:
-        application/json:
-          schema:
-            $ref: '../schemas/AuthUser.yaml'
-    '400':
-      $ref: '../../v3/responses/400.yaml'
-    '401':
-      $ref: '../../v3/responses/401.yaml'
-    '403':
-      $ref: '../../v3/responses/403.yaml'
-    '404':
-      $ref: '../../v3/responses/404.yaml'
-    '429':
-      $ref: '../../v3/responses/429.yaml'
-    '500':
-      $ref: '../../v3/responses/500.yaml'
-
-put:
-  operationId: updateAuthUser
-  tags:
-    - Auth User
-  summary: Auth User Update - Overwrite
-  description: Update an existing user in the authentication system by over overwriting the information with new information.
-  #  security:
-  #    - oauth2: [sp:auth-user:update]
-  parameters:
-    - in: path
-      name: id
-      description: >-
-        Identity ID
-      required: true
-      schema:
-        type: string
  requestBody:
    required: true
    description: |
@@ -152,8 +51,8 @@ delete:
    - Auth User
  summary: Delete an Auth User
  description: Delete an existing user in the authentication system.
-  #  security:
-  #    - oauth2: [sp:auth-user:delete]
+  security:
+    - oauth2: [sp:auth-user:delete]
  parameters:
    - in: path
      name: id
@@ -162,6 +61,7 @@ delete:
      required: true
      schema:
        type: string
+      example: ef38f94347e94562b5bb8424a56397d8
  responses:
    '204':
      $ref: '../../v3/responses/204.yaml'
--- a/idn/sailpoint-api.v3.yaml
+++ b/idn/sailpoint-api.v3.yaml
@@ -167,6 +167,8 @@ tags:
      - Password Change: These include password changes on sources.

      Refer to [Account Activity](https://documentation.sailpoint.com/saas/help/search/index.html#account-activity) for more information about account activities.
+  - name: Auth User
+    description: Authentication service user retrieval and user capabilities update
  - name: Certification Campaigns
    description: |
      Use this API to implement certification campaign functionality.
@@ -371,7 +373,7 @@ tags:
    description: |
      Use this API to implement OAuth client functionality.   
      With this functionality in place, users with the appropriate security scopes can create and configure OAuth clients to use as a way to obtain authorization to use the IdentityNow REST API.
-      Refer to [Authentication](https://developer.sailpoint.com/idn/api/authentication) for more information about OAuth and how it works with the IdentityNow REST API. 
+      Refer to [Authentication](https://developer.sailpoint.com/idn/api/authentication) for more information about OAuth and how it works with the IdentityNow REST API.
  - name: Password Configuration
    description: |
      Use this API to implement organization password configuration functionality. 
@@ -810,6 +812,8 @@ paths:
    $ref: "./v3/paths/account-activity-get-one.yaml"
  /auth-org/network-config:
    $ref: "./v3/paths/auth-org-network-config.yaml"
+  /auth-users/{id}:
+    $ref: "./v3/paths/auth-user.yaml"
  /campaigns:
    $ref: './v3/paths/campaigns.yaml'
  /campaigns/{id}:
--- a/idn/v3/paths/auth-user.yaml
+++ b/idn/v3/paths/auth-user.yaml
@@ -0,0 +1,102 @@
+get:
+  operationId: getAuthUser
+  tags:
+    - Auth User
+  summary: Auth User Details
+  description: >-
+    This API returns the specified user's authentication system details.
+
+    Requires security scope of:  'sp:auth-user:read'
+  parameters:
+    - in: path
+      name: id
+      description: >-
+        Identity ID
+      required: true
+      schema:
+        type: string
+      example: ef38f94347e94562b5bb8424a56397d8
+  security:
+    - oauth2: [sp:auth-user:read]
+  responses:
+    '200':
+      description: The specified user's authentication system details.
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/AuthUser.yaml'
+    '400':
+      $ref: '../../v3/responses/400.yaml'
+    '401':
+      $ref: '../../v3/responses/401.yaml'
+    '403':
+      $ref: '../../v3/responses/403.yaml'
+    '404':
+      $ref: '../../v3/responses/404.yaml'
+    '429':
+      $ref: '../../v3/responses/429.yaml'
+    '500':
+      $ref: '../../v3/responses/500.yaml'
+
+patch:
+  operationId: patchAuthUser
+  tags:
+    - Auth User
+  summary: Auth User Update
+  description: Update an existing user in the authentication system with a PATCH request.
+  security:
+    - oauth2: [sp:auth-user:update]
+  parameters:
+    - in: path
+      name: id
+      description: >-
+        Identity ID
+      required: true
+      schema:
+        type: string
+      example: ef38f94347e94562b5bb8424a56397d8
+  requestBody:
+    required: true
+    description: |
+      A list of auth user update operations according to the [JSON Patch](https://tools.ietf.org/html/rfc6902) standard.
+
+      PATCH can only be applied to the following fields:
+        *   "capabilities"
+
+      A list of valid capabilities can be found using the GET ams/v3/authorization/authorization-capabilities/ endpoint.
+      Capabilities can only be patched if they are administrator assignable, as indicated by the 'adminAssignable' field from the output of list authorization-capabilities.
+      Capabilities that have a legacy group ('legacyGroup' field) need to be patched using the legacyGroup name (e.g. 'ORG_ADMIN').
+      Capabilities that are adminAssignable but do not have a legacyGroup can be patched using the ams id (e.g. 'cam:new-role').
+
+      A 400.1.1 Illegal update attempt detail code indicates that you attempted to PATCH a field that is not allowed.
+
+      Requires security scope of 'sp:auth-user:update'
+    content:
+      application/json-patch+json:
+        schema:
+          type: array
+          items:
+            $ref: '../schemas/JsonPatchOperation.yaml'
+        example:
+            - op: "replace"
+              path: "/capabilities"
+              value: ["ORG_ADMIN"]
+  responses:
+    '200':
+      description: Auth user updated.
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/AuthUser.yaml'
+    '400':
+      $ref: '../../v3/responses/400.yaml'
+    '401':
+      $ref: '../../v3/responses/401.yaml'
+    '403':
+      $ref: '../../v3/responses/403.yaml'
+    '404':
+      $ref: '../../v3/responses/404.yaml'
+    '429':
+      $ref: '../../v3/responses/429.yaml'
+    '500':
+      $ref: '../../v3/responses/500.yaml'
--- a/idn/v3/schemas/AuthUser.yaml
+++ b/idn/v3/schemas/AuthUser.yaml
@@ -0,0 +1,74 @@
+type: object
+properties:
+  tenant:
+    type: string
+    description: Tenant name.
+    example: "test-tenant"
+  id:
+    type: string
+    description: Identity ID.
+    example: 2c91808458ae7a4f0158b1bbf8af0628
+  uid:
+    type: string
+    description: Identity unique identitifier.
+    example: "will.smith"
+  profile:
+    type: string
+    description: ID of the auth profile associated with this auth user.
+    example: 2c91808458ae7a4f0158b1bbf8af0756
+  identificationNumber:
+    type: string
+    description: Auth user employee number.
+    example: "19-5588452"
+  email:
+    type: string
+    description: Auth user's email.
+    example: william.smith@example.com
+  phone:
+    type: string
+    description: Auth user's phone number.
+    example: "5555555555"
+  workPhone:
+    type: string
+    description: Auth user's work phone number.
+    example: "5555555555"
+  personalEmail:
+    type: string
+    description: Auth user's personal email.
+    example: william.smith@example.com
+  firstname:
+    type: string
+    description: Auth user's first name.
+    example: Will
+  lastname:
+    type: string
+    description: Auth user's last name.
+    example: Smith
+  displayName:
+    type: string
+    description: Auth user's name in displayed format.
+    example: Will Smith
+  alias:
+    type: string
+    description: Auth user's alias.
+    example: will.smith
+  lastPasswordChangeDate:
+    type: string
+    description: the date of last password change
+    example: "2021-03-08T22:37:33.901Z"
+  lastLoginTimestamp:
+    description: Timestamp of the last login (long type value).
+    type: integer
+    format: int64
+    example: 1656327185832
+  currentLoginTimestamp:
+    description: Timestamp of the current login (long type value).
+    type: integer
+    format: int64
+    example: 1656327185832
+  capabilities:
+    description: Array of capabilities for this auth user.
+    type: array
+    items:
+      type: string
+      example: "ORG_ADMIN"