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.