openapi: 3.1.0
info:
  title: Identity Security Cloud V3 Access Profiles API
  description: Use these APIs to interact with the Identity Security Cloud platform to achieve repeatable, automated processes with greater scalability. The V3 APIs provide core endpoints covering access profiles, certifications, identities, roles, search, sources, transforms, workflows, and more. We encourage you to join the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss to connect with other developers using our APIs.
  termsOfService: https://developer.sailpoint.com/discuss/tos
  contact:
    name: Developer Relations
    url: https://developer.sailpoint.com/discuss/api-help
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
    identifier: MIT
  version: 3.0.0
servers:
- url: https://{tenant}.api.identitynow.com/v3
  description: Production API server.
  variables:
    tenant:
      default: sailpoint
      description: The name of your tenant, typically your company's name.
- url: https://{apiUrl}/v3
  description: V3 API server.
  variables:
    apiUrl:
      default: sailpoint.api.identitynow.com
      description: The API URL of your tenant.
security:
- oauth2: []
- personalAccessToken: []
tags:
- name: Access Profiles
  description: Use this API to implement and customize access profile functionality. Access profiles group entitlements, which represent access rights on sources. For example, an Active Directory source can have multiple entitlements grouped into an access profile such as 'AD Developers' combining 'Employees' and 'Developers' entitlements. Access profiles are used in provisioning, certifications, access requests, and roles.
  externalDocs:
    description: SailPoint Access Profiles Documentation
    url: https://developer.sailpoint.com/docs/api/v3/access-profiles/
paths:
  /access-profiles:
    get:
      operationId: listAccessProfiles
      tags:
      - Access Profiles
      summary: List access profiles
      description: Get a list of access profiles. When you filter for access profiles that have the '+' symbol in their names, the response is blank.
      parameters:
      - name: for-subadmin
        in: query
        description: Filters the returned list according to what is visible to the indicated ROLE_SUBADMIN or SOURCE_SUBADMIN identity. The value is either an identity ID or the special value 'me' for the calling identity's ID.
        required: false
        schema:
          type: string
        example: 8c190e6787aa4ed9a90bd9d5344523fb
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Count'
      - name: filters
        in: query
        description: 'Filter results using the standard syntax. Filtering is supported for the following fields and operators: id (eq, in), name (eq, sw), created (gt, ge, le), modified (gt, lt, ge, le), owner.id (eq, in), requestable (eq), source.id (eq, in). Supported composite operators are ''and'' and ''or''.'
        required: false
        schema:
          type: string
        example: name eq "SailPoint Support"
      - name: sorters
        in: query
        description: 'Sort results using the standard syntax. Sorting is supported for the following fields: name, created, modified.'
        required: false
        schema:
          type: string
        example: name,-modified
      - name: for-segment-ids
        in: query
        description: Filters access profiles to only those assigned to the segment(s) with the specified IDs. If segmentation is unavailable, specifying this parameter results in an error.
        required: false
        schema:
          type: string
        example: 0b5c9f25-83c6-4762-9073-e38f7bb2ae26,2e8d8180-24bc-4d21-91c6-7affdb473b0d
      - name: include-unsegmented
        in: query
        description: Indicates whether the response should include unsegmented access profiles. If for-segment-ids is absent or empty, specifying this as false results in an error.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: List of access profiles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessProfile'
          headers:
            X-Total-Count:
              description: Total number of results matching the query.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oauth2:
        - idn:access-profile:read
    post:
      operationId: createAccessProfile
      tags:
      - Access Profiles
      summary: Create an access profile
      description: Create an access profile. A user with ROLE_SUBADMIN or SOURCE_SUBADMIN authority must be associated with the access profile's source. The maximum supported length for the description field is 2000 characters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessProfile'
      responses:
        '201':
          description: Access profile created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oauth2:
        - idn:access-profile:manage
        - idn:entitlement:read
        - idn:identity:read
        - idn:sources:read
  /access-profiles/{id}:
    get:
      operationId: getAccessProfile
      tags:
      - Access Profiles
      summary: Get an access profile
      description: Get an access profile by its ID.
      parameters:
      - name: id
        in: path
        description: The access profile ID.
        required: true
        schema:
          type: string
        example: 2c91808a7190d06e01719938fcd20792
      responses:
        '200':
          description: An access profile object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oauth2:
        - idn:access-profile:read
    patch:
      operationId: patchAccessProfile
      tags:
      - Access Profiles
      summary: Patch an access profile
      description: Update an existing access profile using a JSON Patch document. The maximum supported length for the description field is 2000 characters.
      parameters:
      - name: id
        in: path
        description: The access profile ID.
        required: true
        schema:
          type: string
        example: 2c91808a7190d06e01719938fcd20792
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/JsonPatchOperation'
      responses:
        '200':
          description: Updated access profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oauth2:
        - idn:access-profile:manage
    delete:
      operationId: deleteAccessProfile
      tags:
      - Access Profiles
      summary: Delete an access profile
      description: Delete an existing access profile by its ID. The access profile must not be in use by any roles.
      parameters:
      - name: id
        in: path
        description: The access profile ID.
        required: true
        schema:
          type: string
        example: 2c91808a7190d06e01719938fcd20792
      responses:
        '204':
          description: Access profile deleted successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oauth2:
        - idn:access-profile:manage
  /access-profiles/{id}/entitlements:
    get:
      operationId: listAccessProfileEntitlements
      tags:
      - Access Profiles
      summary: List access profile entitlements
      description: Get a list of entitlements associated with the specified access profile.
      parameters:
      - name: id
        in: path
        description: The access profile ID.
        required: true
        schema:
          type: string
        example: 2c91808a7190d06e01719938fcd20792
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Count'
      - name: filters
        in: query
        description: 'Filter results using the standard syntax. Filtering is supported for the following fields: name (eq, sw).'
        required: false
        schema:
          type: string
      - name: sorters
        in: query
        description: 'Sort results using the standard syntax. Sorting is supported for the following fields: name, created, modified.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: List of entitlements for the access profile.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entitlement'
          headers:
            X-Total-Count:
              description: Total number of results matching the query.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oauth2:
        - idn:access-profile:read
  /access-profiles/bulk-delete:
    post:
      operationId: bulkDeleteAccessProfiles
      tags:
      - Access Profiles
      summary: Bulk delete access profiles
      description: Delete one or more access profiles in a single request. The access profiles must not be in use by any roles or applications. Returns details about which profiles were deleted and which failed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessProfileBulkDeleteRequest'
      responses:
        '200':
          description: Bulk delete results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessProfileBulkDeleteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - oauth2:
        - idn:access-profile:manage
components:
  schemas:
    AccessProfileSourceRef:
      type: object
      description: Reference to the source associated with the access profile.
      properties:
        id:
          type: string
          description: The source ID.
          examples:
          - 2c91809773dee3610173fdb1b6969d4e
        type:
          type: string
          description: The source object type.
          enum:
          - SOURCE
          examples:
          - SOURCE
        name:
          type: string
          description: The source name.
          examples:
          - ODS-AD-SOURCE
    Entitlement:
      type: object
      description: An entitlement representing access rights on a source.
      properties:
        id:
          type: string
          description: The entitlement ID.
          examples:
          - 2c91809773dee32014e13e122092014e
        name:
          type: string
          description: The entitlement name.
          examples:
          - CN=entitlement.490efde5,OU=OrgCo,OU=ServiceDept,DC=HQAD,DC=local
        description:
          type:
          - string
          - 'null'
          description: The entitlement description.
          examples:
          - Entitlement granting access to the developer tools
        attribute:
          type: string
          description: The name of the entitlement attribute.
          examples:
          - memberOf
        value:
          type: string
          description: The value of the entitlement.
          examples:
          - CN=entitlement.490efde5,OU=OrgCo,OU=ServiceDept,DC=HQAD,DC=local
        sourceSchemaObjectType:
          type: string
          description: The object type of the source schema.
          examples:
          - group
        privileged:
          type: boolean
          description: Whether the entitlement is privileged.
          default: false
        cloudGoverned:
          type: boolean
          description: Whether the entitlement is governed in the cloud.
          default: false
        created:
          type: string
          format: date-time
          description: Date and time the entitlement was created.
          readOnly: true
        modified:
          type: string
          format: date-time
          description: Date and time the entitlement was last modified.
          readOnly: true
        source:
          $ref: '#/components/schemas/EntitlementSourceRef'
        owner:
          $ref: '#/components/schemas/OwnerReference'
    Revocability:
      type:
      - object
      - 'null'
      description: Revocation request configuration for the object.
      properties:
        commentsRequired:
          type: boolean
          default: false
          description: Whether comments are required for revocation requests.
        denialCommentsRequired:
          type: boolean
          default: false
          description: Whether comments are required for denial of revocation requests.
        approvalSchemes:
          type: array
          description: List of approval schemes for revocation requests.
          items:
            $ref: '#/components/schemas/ApprovalScheme'
    AccessProfile:
      type: object
      description: An access profile groups entitlements that represent access rights on sources. Access profiles are used in provisioning, certifications, access requests, and roles.
      required:
      - name
      - owner
      - source
      properties:
        id:
          type: string
          description: The access profile ID.
          readOnly: true
          examples:
          - 2c91808a7190d06e01719938fcd20792
        name:
          type: string
          description: The access profile name.
          examples:
          - Employee-database-read-write
        description:
          type:
          - string
          - 'null'
          description: The access profile description. Maximum supported length is 2000 characters.
          maxLength: 2000
          examples:
          - Collection of entitlements to read/write the employee database
        created:
          type: string
          format: date-time
          description: Date and time the access profile was created.
          readOnly: true
          examples:
          - '2021-03-01T22:32:58.104Z'
        modified:
          type: string
          format: date-time
          description: Date and time the access profile was last modified.
          readOnly: true
          examples:
          - '2021-03-02T20:22:28.104Z'
        enabled:
          type: boolean
          default: false
          description: Whether the access profile is enabled. If enabled, you must include at least one entitlement.
          examples:
          - true
        owner:
          $ref: '#/components/schemas/OwnerReference'
        source:
          $ref: '#/components/schemas/AccessProfileSourceRef'
        entitlements:
          type:
          - array
          - 'null'
          description: List of entitlements associated with the access profile. If enabled is false, this can be empty. Otherwise, it must contain at least one entitlement.
          items:
            $ref: '#/components/schemas/EntitlementRef'
        requestable:
          type: boolean
          default: true
          description: Whether the access profile is requestable via access requests.
          examples:
          - true
        accessRequestConfig:
          $ref: '#/components/schemas/Requestability'
        revocationRequestConfig:
          $ref: '#/components/schemas/Revocability'
        segments:
          type:
          - array
          - 'null'
          description: List of segment IDs the access profile is assigned to.
          items:
            type: string
          examples:
          - - f7b1b8a3-5fed-4fd4-ad29-82014e137e19
            - 29cb6c06-1da8-43ea-8be4-b3125f248f2a
    ErrorResponseDto:
      type: object
      description: Error response body.
      properties:
        detailCode:
          type: string
          description: Fine-grained error code providing more detail.
          examples:
          - 400.1 Bad Request Content
        trackingId:
          type: string
          description: Unique tracking ID for the error.
          examples:
          - e7eab60924f64aa284175b9fa3309599
        messages:
          type: array
          description: Generic localized reason for error.
          items:
            type: object
            properties:
              locale:
                type: string
                description: The locale for the message text.
                examples:
                - en-US
              localeOrigin:
                type: string
                description: An indicator of how the locale was selected.
                enum:
                - DEFAULT
                - REQUEST
                examples:
                - DEFAULT
              text:
                type: string
                description: The actual text of the error message.
                examples:
                - The request was syntactically correct but its content is semantically invalid.
        causes:
          type: array
          description: Plain-text descriptive reasons to provide additional detail to the text provided in the messages field.
          items:
            type: object
            properties:
              locale:
                type: string
                examples:
                - en-US
              localeOrigin:
                type: string
                enum:
                - DEFAULT
                - REQUEST
              text:
                type: string
    AccessProfileBulkDeleteResponse:
      type: object
      description: Response body for bulk deleting access profiles.
      properties:
        pending:
          type: array
          description: IDs of access profiles queued for deletion.
          items:
            type: string
        inUse:
          type: array
          description: Details about access profiles that could not be deleted because they are in use.
          items:
            type: object
            properties:
              accessProfileId:
                type: string
                description: The access profile ID.
              usedBy:
                type: array
                description: Objects using this access profile.
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    id:
                      type: string
                    name:
                      type: string
    EntitlementSourceRef:
      type: object
      description: Reference to the source associated with the entitlement.
      properties:
        id:
          type: string
          description: The source ID.
          examples:
          - 2c9180835d191a86015d28455b4b232a
        type:
          type: string
          description: The source object type.
          examples:
          - SOURCE
        name:
          type: string
          description: The source name.
          examples:
          - ODS-AD-SOURCE
    OwnerReference:
      type: object
      description: Reference to the owner of the object.
      properties:
        type:
          type: string
          description: Owner type. Must be either left null or set to IDENTITY on input, otherwise a 400 Bad Request error will result.
          enum:
          - IDENTITY
          examples:
          - IDENTITY
        id:
          type: string
          description: The owner's identity ID.
          examples:
          - 2c9180a46faadee4016fb4e018c20639
        name:
          type: string
          description: The owner's name. If set, it must match the current value of the owner's display name, otherwise a 400 Bad Request error will result.
          examples:
          - support
    AccessProfileBulkDeleteRequest:
      type: object
      description: Request body for bulk deleting access profiles.
      required:
      - accessProfileIds
      properties:
        accessProfileIds:
          type: array
          description: List of access profile IDs to delete.
          items:
            type: string
          examples:
          - - 2c91808a7190d06e01719938fcd20792
            - 2c91808a7190d06e01719938fcd20793
        bestEffortOnly:
          type: boolean
          default: false
          description: If true, silently skip access profiles that cannot be deleted.
    EntitlementRef:
      type: object
      description: Reference to an entitlement.
      properties:
        type:
          type: string
          description: The entitlement object type.
          enum:
          - ENTITLEMENT
          examples:
          - ENTITLEMENT
        id:
          type: string
          description: The entitlement ID.
          examples:
          - 2c91809773dee32014e13e122092014e
        name:
          type: string
          description: The entitlement display name.
          examples:
          - CN=entitlement.490efde5,OU=OrgCo,OU=ServiceDept,DC=HQAD,DC=local
    Requestability:
      type:
      - object
      - 'null'
      description: Access request configuration for the object.
      properties:
        commentsRequired:
          type: boolean
          default: false
          description: Whether comments are required for access requests.
        denialCommentsRequired:
          type: boolean
          default: false
          description: Whether comments are required for denial of access requests.
        approvalSchemes:
          type: array
          description: List of approval schemes for access requests.
          items:
            $ref: '#/components/schemas/ApprovalScheme'
    ApprovalScheme:
      type: object
      description: An approval scheme defining the approval process.
      properties:
        approverType:
          type: string
          description: The type of approver. APP_OWNER is the application owner, OWNER is the access profile/role owner, SOURCE_OWNER is the source owner, MANAGER is the requesting user's manager, and GOVERNANCE_GROUP is a governance group.
          enum:
          - APP_OWNER
          - OWNER
          - SOURCE_OWNER
          - MANAGER
          - GOVERNANCE_GROUP
          examples:
          - MANAGER
        approverId:
          type:
          - string
          - 'null'
          description: The ID of the approver. Only required when approverType is GOVERNANCE_GROUP.
          examples:
          - 46c79c6399252b1a80dbdff5e2b1d4b7
    JsonPatchOperation:
      type: object
      description: A JSON Patch operation as defined in RFC 6902.
      required:
      - op
      - path
      properties:
        op:
          type: string
          description: The operation to perform.
          enum:
          - add
          - remove
          - replace
          - move
          - copy
          - test
          examples:
          - replace
        path:
          type: string
          description: The JSON pointer path for the operation.
          examples:
          - /description
        value:
          description: The value for the operation (required for add, replace, test).
  responses:
    InternalServerError:
      description: Internal Server Error - Returned if there is an unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
    BadRequest:
      description: Client Error - Returned if the request body is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
    TooManyRequests:
      description: Too Many Requests - Returned in response to too many requests in a given period of time, rate limited. The Retry-After header in the response includes how long to wait before trying again.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
    NotFound:
      description: Not Found - Returned if the specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
    Forbidden:
      description: Forbidden - Returned if the user you are running as does not have access to this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
    Unauthorized:
      description: Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
  parameters:
    Count:
      name: count
      in: query
      description: If true, the total count of items in the full result set is included in the X-Total-Count response header. Only items in the current page are returned. Requesting a count can decrease performance.
      required: false
      schema:
        type: boolean
        default: false
    Offset:
      name: offset
      in: query
      description: Offset into the full result set. Usually specified with limit to paginate through the results.
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    Limit:
      name: limit
      in: query
      description: Maximum number of results to return. Maximum value is 250.
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 250
        default: 250
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication. Use client credentials or authorization code flow to obtain access tokens.
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.api.identitynow.com/oauth/token
          scopes:
            idn:identity:read: Read identity information
            idn:identity-profile:read: Read identity profiles
            idn:identity-profile:manage: Manage identity profiles
            idn:access-profile:read: Read access profiles
            idn:access-profile:manage: Manage access profiles
            idn:entitlement:read: Read entitlements
            idn:sources:read: Read sources
            idn:role-unchecked:read: Read roles
            idn:role-unchecked:manage: Manage roles
            idn:certification:read: Read certifications
            idn:certification:manage: Manage certifications
        authorizationCode:
          authorizationUrl: https://{tenant}.identitynow.com/oauth/authorize
          tokenUrl: https://{tenant}.api.identitynow.com/oauth/token
          scopes:
            idn:identity:read: Read identity information
            idn:identity-profile:read: Read identity profiles
            idn:identity-profile:manage: Manage identity profiles
            idn:access-profile:read: Read access profiles
            idn:access-profile:manage: Manage access profiles
            idn:entitlement:read: Read entitlements
            idn:sources:read: Read sources
            idn:role-unchecked:read: Read roles
            idn:role-unchecked:manage: Manage roles
            idn:certification:read: Read certifications
            idn:certification:manage: Manage certifications
    personalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Personal access token (PAT) authentication. Generate a PAT in Identity Security Cloud and use it as a bearer token.