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.