openapi: 3.1.0
info:
  title: Identity Security Cloud V3 Access Profiles Identities 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: Identities
  description: Use this API to retrieve and manage public identity information. Public identities represent users within the Identity Security Cloud platform, including their attributes, lifecycle state, and manager relationships.
  externalDocs:
    description: SailPoint Identities Documentation
    url: https://developer.sailpoint.com/docs/api/v3/get-public-identities/
paths:
  /public-identities:
    get:
      operationId: getPublicIdentities
      tags:
      - Identities
      summary: List public identities
      description: Get a list of public identities. This endpoint returns a paged list of public identity objects that can be filtered and sorted.
      parameters:
      - name: add-core-filters
        in: query
        description: Set to true to exclude incomplete identities and uncorrelated accounts from the results.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Count'
      - name: filters
        in: query
        description: 'Filter results using the standard syntax described in V3 API Standard Collection Parameters. Filtering is supported for the following fields and operators: id (eq, in), name (eq, sw, co), alias (eq, sw, co), email (eq, sw, co), status (eq).'
        required: false
        schema:
          type: string
        example: name eq "John Smith"
      - name: sorters
        in: query
        description: 'Sort results using the standard syntax. Sorting is supported for the following fields: name, alias, email.'
        required: false
        schema:
          type: string
        example: name,-email
      responses:
        '200':
          description: List of public identities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicIdentity'
          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:identity:read
  /public-identities/{id}:
    get:
      operationId: getPublicIdentity
      tags:
      - Identities
      summary: Get a public identity
      description: Get the details of a public identity by its ID.
      parameters:
      - name: id
        in: path
        description: The identity ID.
        required: true
        schema:
          type: string
        example: 2c9180857182305e0171993735622948
      responses:
        '200':
          description: A public identity object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicIdentity'
        '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:identity:read
  /identity-profiles:
    get:
      operationId: listIdentityProfiles
      tags:
      - Identities
      summary: List identity profiles
      description: Get a list of identity profiles. Identity profiles define how identity attributes are mapped from source account attributes and configure lifecycle states.
      parameters:
      - $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: id (eq, in), name (eq, sw), priority (eq, gt, lt, ge, le).'
        required: false
        schema:
          type: string
        example: name eq "HR Profile"
      - name: sorters
        in: query
        description: 'Sort results using the standard syntax. Sorting is supported for the following fields: name, priority, created, modified.'
        required: false
        schema:
          type: string
        example: name,-priority
      responses:
        '200':
          description: List of identity profiles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityProfile'
          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:identity-profile:read
    post:
      operationId: createIdentityProfile
      tags:
      - Identities
      summary: Create an identity profile
      description: Create an identity profile. An identity profile defines the mapping between source account attributes and identity attributes and configures lifecycle states for identities.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProfile'
      responses:
        '201':
          description: Identity profile created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProfile'
        '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:identity-profile:manage
  /identity-profiles/{identity-profile-id}:
    get:
      operationId: getIdentityProfile
      tags:
      - Identities
      summary: Get an identity profile
      description: Get the details of an identity profile by its ID.
      parameters:
      - name: identity-profile-id
        in: path
        description: The identity profile ID.
        required: true
        schema:
          type: string
        example: 2b838de9-db9b-abcf-e646-d4f274ad4238
      responses:
        '200':
          description: An identity profile object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProfile'
        '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:identity-profile:read
    patch:
      operationId: updateIdentityProfile
      tags:
      - Identities
      summary: Update an identity profile
      description: Update an existing identity profile using a JSON Patch document.
      parameters:
      - name: identity-profile-id
        in: path
        description: The identity profile ID.
        required: true
        schema:
          type: string
        example: 2b838de9-db9b-abcf-e646-d4f274ad4238
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/JsonPatchOperation'
      responses:
        '200':
          description: Updated identity profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProfile'
        '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:identity-profile:manage
    delete:
      operationId: deleteIdentityProfile
      tags:
      - Identities
      summary: Delete an identity profile
      description: Delete an identity profile by its ID.
      parameters:
      - name: identity-profile-id
        in: path
        description: The identity profile ID.
        required: true
        schema:
          type: string
        example: 2b838de9-db9b-abcf-e646-d4f274ad4238
      responses:
        '202':
          description: Identity profile delete request accepted. This is a long-running asynchronous operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResultSimplified'
        '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:identity-profile:manage
components:
  responses:
    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'
    NotFound:
      description: Not Found - Returned if the specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
    InternalServerError:
      description: Internal Server Error - Returned if there is an unexpected error.
      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'
    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'
    BadRequest:
      description: Client Error - Returned if the request body is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseDto'
  schemas:
    TaskResultSimplified:
      type: object
      description: A simplified task result for asynchronous operations.
      properties:
        id:
          type: string
          description: The task ID.
          examples:
          - 464ae7bf-791e-49fd-b746-06a2e4a89635
        type:
          type: string
          description: The type of task.
          examples:
          - TASK_RESULT
        name:
          type:
          - string
          - 'null'
          description: The task name.
    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
    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
    SourceReference:
      type: object
      description: Reference to a source.
      properties:
        type:
          type: string
          description: The source object type.
          enum:
          - SOURCE
          examples:
          - SOURCE
        id:
          type: string
          description: The source ID.
          examples:
          - 2c9180835d191a86015d28455b4b232a
        name:
          type: string
          description: The source name.
          examples:
          - HR Active Directory
    IdentityReference:
      type:
      - object
      - 'null'
      description: Reference to an identity.
      properties:
        type:
          type: string
          description: The type of the referenced object.
          enum:
          - IDENTITY
          examples:
          - IDENTITY
        id:
          type: string
          description: The identity ID.
          examples:
          - 2c9180a46faadee4016fb4e018c20639
        name:
          type: string
          description: Human-readable display name of the identity.
          examples:
          - Thomas Edison
    IdentityProfile:
      type: object
      description: An identity profile defines the mapping between source account attributes and identity attributes and configures lifecycle states for identities.
      required:
      - name
      - authoritativeSource
      properties:
        id:
          type: string
          description: The identity profile ID.
          readOnly: true
          examples:
          - 2b838de9-db9b-abcf-e646-d4f274ad4238
        name:
          type: string
          description: The identity profile name.
          examples:
          - HR Employees
        description:
          type:
          - string
          - 'null'
          description: The identity profile description.
          examples:
          - My custom flat file profile
        owner:
          $ref: '#/components/schemas/OwnerReference'
        priority:
          type: integer
          format: int64
          description: The identity profile priority.
          examples:
          - 10
        authoritativeSource:
          $ref: '#/components/schemas/SourceReference'
        identityRefreshRequired:
          type: boolean
          default: false
          description: Set to true if an identity refresh is necessary, typically when a change has been made on the source.
          examples:
          - true
        identityCount:
          type: integer
          format: int32
          description: Number of identities belonging to the identity profile.
          readOnly: true
          examples:
          - 8
        hasTimeBasedAttr:
          type: boolean
          default: false
          description: Indicates the value of the requiresPeriodicRefresh attribute for the identity profile.
          examples:
          - true
        created:
          type: string
          format: date-time
          description: Date and time the profile was created.
          readOnly: true
          examples:
          - '2023-01-03T21:16:22.432Z'
        modified:
          type: string
          format: date-time
          description: Date and time the profile was last modified.
          readOnly: true
          examples:
          - '2023-01-05T18:40:35.772Z'
    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).
    IdentityAttribute:
      type: object
      description: A public identity attribute key-value pair.
      properties:
        key:
          type: string
          description: The attribute key.
          examples:
          - country
        name:
          type: string
          description: Human-readable display name of the attribute.
          examples:
          - Country
        value:
          type:
          - string
          - 'null'
          description: The attribute value.
          examples:
          - US
    PublicIdentity:
      type: object
      description: Details about a public identity.
      properties:
        id:
          type: string
          description: The identity ID.
          examples:
          - 2c9180857182305e0171993735622948
        name:
          type: string
          description: Human-readable display name of the identity.
          examples:
          - Alison Ferguso
        alias:
          type: string
          description: Alternate unique identifier for the identity.
          examples:
          - alison.ferguso
        email:
          type:
          - string
          - 'null'
          description: Email address of the identity.
          examples:
          - alison.ferguso@acme-solar.com
        status:
          type:
          - string
          - 'null'
          description: The lifecycle status for the identity.
          examples:
          - Active
        identityState:
          type:
          - string
          - 'null'
          description: The current state of the identity, which determines how Identity Security Cloud interacts with the identity. Active identities are included in identity picklists in Request Center, identity processing, and more. Inactive identities are excluded from these features.
          enum:
          - ACTIVE
          - INACTIVE_SHORT_TERM
          - INACTIVE_LONG_TERM
          - null
          examples:
          - ACTIVE
        manager:
          $ref: '#/components/schemas/IdentityReference'
        attributes:
          type: array
          description: The public identity attributes of the identity.
          items:
            $ref: '#/components/schemas/IdentityAttribute'
  parameters:
    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
    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
    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.