Identity Sources

The Okta Identity Source API provides a mechanism to synchronize an HR source (the custom identity source) with Okta user profiles in an org. See Build an Anything-as-a-Source custom client integration.

List all identity source sessions
OAuth 2.0 scopes:
  • okta.identitySources.read

Lists all identity source sessions for the given identity source instance

Request
path Parameters
identitySourceId
required
string

The ID of the identity source for which the session is created

Example: 0oa3l6l6WK6h0R0QW0g4
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/identity-sources/{identitySourceId}/sessions
Request samples 
Response samples 
application/json
[
  • {
    • "id": "aps1qqonvr2SZv6o70h8",
    • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
    • "status": "CREATED",
    • "importType": "INCREMENTAL",
    • "created": "2022-04-04T15:56:05.000Z",
    • "lastUpdated": "2022-05-05T16:15:44.000Z"
    },
  • {
    • "id": "aps1quck606ngubVq0h8",
    • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
    • "status": "TRIGGERED",
    • "importType": "INCREMENTAL",
    • "created": "2022-04-04T16:56:05.000Z",
    • "lastUpdated": "2022-05-05T17:15:44.000Z"
    },
  • {
    • "id": "aps1qzy2acb5jDlUc0h8",
    • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
    • "status": "IN_PROGRESS",
    • "importType": "INCREMENTAL",
    • "created": "2022-04-04T17:56:05.000Z",
    • "lastUpdated": "2022-05-05T18:15:44.000Z"
    },
  • {
    • "id": "aps1qqne8c1JHkMdF0h8",
    • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
    • "status": "EXPIRED",
    • "importType": "INCREMENTAL",
    • "created": "2022-04-04T18:56:05.000Z",
    • "lastUpdated": "2022-05-05T19:15:44.000Z"
    },
  • {
    • "id": "aps1qqonvr2SZv6o70h8",
    • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
    • "status": "CLOSED",
    • "importType": "INCREMENTAL",
    • "created": "2022-04-04T19:56:05.000Z",
    • "lastUpdated": "2022-05-05T20:15:44.000Z"
    }
]
Create an identity source session
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Creates an identity source session for the given identity source instance


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions
Request samples 
Response samples 
application/json
{
  • "id": "aps1qqonvr2SZv6o70h8",
  • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
  • "status": "CREATED",
  • "importType": "INCREMENTAL",
  • "created": "2022-04-04T15:56:05.000Z",
  • "lastUpdated": "2022-05-05T16:15:44.000Z"
}
Retrieve an identity source session
OAuth 2.0 scopes: 
  • okta.identitySources.read
Retrieves an identity source session for a given identity source ID and session ID


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}
Request samples 
Response samples 
application/json
{
  • "id": "aps1qqonvr2SZv6o70h8",
  • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
  • "status": "CREATED",
  • "importType": "INCREMENTAL",
  • "created": "2022-04-04T15:56:05.000Z",
  • "lastUpdated": "2022-05-05T16:15:44.000Z"
}
Delete an identity source session
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Deletes an identity source session for a given identity source ID and session Id


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Upload the data to be deleted in Okta
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Uploads external IDs of entities that need to be deleted in Okta from the identity source for the given session


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Request Body schema: application/json
entityType
string
The type of data to bulk delete in a session. Currently, only USERS is supported.


 Value: "USERS"  
Array of objects (IdentitySourceUserProfileForDelete) 
Array of profiles to be deleted


 
 Array 
externalId
string  <= 512 characters 
The external ID of the entity that needs to be deleted in Okta


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}/bulk-delete
Request samples 
application/json
{
  • "entityType": "USERS",
  • "profiles": [
    • {
      },
    • {
      },
    • {
      }
    ]
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Upload the group memberships to be deleted in Okta
Early Access
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Uploads the group memberships that need to be deleted in Okta from the identity source for the given session


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Request Body schema: application/json
Array of objects (IdentitySourceGroupMembershipsDeleteProfile)   [ 1 .. 200 ] items 
Array of group memberships that need to be deleted in Okta


 
 Array ([ 1 .. 200 ] items)
groupExternalId
string  <= 255 characters 
The external ID of the group whose memberships need to be deleted in Okta


 
memberExternalIds
Array of strings
Array of external IDs of member profiles that need to be inserted in this group in Okta


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}/bulk-group-memberships-delete
Request samples 
application/json
{
  • "memberships": [
    • {
      },
    • {
      }
    ]
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Upload the group memberships to be upserted in Okta
Early Access
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Uploads the group memberships that need to be inserted or updated in Okta from the identity source for the given session


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Request Body schema: application/json
Array of objects (IdentitySourceGroupMembershipsUpsertProfile)   [ 1 .. 200 ] items 
Array of group memberships that need to be inserted or updated in Okta


 
 Array ([ 1 .. 200 ] items)
groupExternalId
string  <= 255 characters 
The external ID of the group whose memberships need to be inserted or updated in Okta


 
memberExternalIds
Array of strings
Array of external IDs of member profiles that need to be inserted in this group in Okta


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}/bulk-group-memberships-upsert
Request samples 
application/json
{
  • "memberships": [
    • {
      },
    • {
      }
    ]
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Upload the group external IDs to be deleted in Okta
Early Access
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Uploads external IDs of groups that need to be deleted in Okta from the identity source for the given session


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Request Body schema: application/json
externalIds
Array of strings  [ 1 .. 200 ] items 
Array of external IDs of groups that need to be deleted in Okta


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}/bulk-groups-delete
Request samples 
application/json
{
  • "externalIds": [
    • "GROUPEXT123456784C2IF",
    • "GROUPEXT123456784C3IF",
    • "GROUPEXT123456784C4IF"
    ]
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Upload the group profiles without memberships to be upserted in Okta
Early Access
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Uploads the group profiles without memberships that need to be inserted or updated in Okta from the identity source for the given session


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Request Body schema: application/json
Array of objects  [ 1 .. 200 ] items 
Array of group profiles that needs to be inserted or updated in Okta


 
 Array ([ 1 .. 200 ] items)
externalId
string  <= 255 characters 
The external ID of the group that needs to be created or updated in Okta


 
object (IdentitySourceGroupProfileForUpsert) 
Contains a set of external group attributes and their values that are mapped to Okta standard properties. See the group profile object and Declaration of a Custom Identity Source Schema in Using anything as a source.




Note: Profile attributes can only be of the string type.




 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}/bulk-groups-upsert
Request samples 
application/json
{
  • "profiles": [
    • {
      },
    • {
      }
    ]
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Upload the data to be upserted in Okta
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Uploads entities that need to be inserted or updated in Okta from the identity source for the given session


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Request Body schema: application/json
entityType
string
The type of data to upsert into the session. Currently, only USERS is supported.


 Value: "USERS"  
Array of objects
Array of user profiles to be uploaded


 
 Array 
externalId
string  <= 512 characters 
The external ID of the entity that needs to be created or updated in Okta


 
object (IdentitySourceUserProfileForUpsert) 
Contains a set of external user attributes and their values that are mapped to Okta standard and custom profile properties. See the profile object and Declaration of a Custom Identity Source Schema in Using anything as a source.




Note: Profile attributes can only be of the string type.




 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}/bulk-upsert
Request samples 
application/json
{
  • "entityType": "USERS",
  • "profiles": [
    • {
      }
    ]
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Start the import from the identity source
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Starts the import from the identity source described by the uploaded bulk operations


Request 
path Parameters
identitySourceId
required
string
The ID of the identity source for which the session is created


 
 Example:  0oa3l6l6WK6h0R0QW0g4
sessionId
required
string
The ID of the identity source session


 
 Example:  aps1qqonvr2SZv6o70h8
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/sessions/{sessionId}/start-import
Request samples 
Response samples 
application/json
[
  • {
    • "id": "aps1qqonvr2SZv6o70h8",
    • "identitySourceId": "0oa3l6l6WK6h0R0QW0g4",
    • "status": "TRIGGERED",
    • "importType": "INCREMENTAL",
    • "created": "2022-04-04T15:56:05.000Z",
    • "lastUpdated": "2022-05-05T18:15:44.000Z"
    }
]