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.

Create an identity source group
OAuth 2.0 scopes:
  • okta.identitySources.manage

Creates a group in an identity source 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
Request Body schema: application/json
externalId
string <= 255 characters

The external ID of the identity source group to be created

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.

description
string or null <= 1024 characters

Description of the group

displayName
string [ 1 .. 255 ] characters

Name of the group

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/identity-sources/{identitySourceId}/groups
Request samples
application/json
{
  • "externalId": "GROUPEXT123456784C2IF",
  • "profile": {
    • "displayName": "West Coast users",
    • "description": "All users West of The Rockies"
    }
}
Response samples
application/json
{
  • "id": "00gsl4xM9ys8TdnbZ0g4",
  • "externalId": "GROUPEXT123456784C2IF",
  • "profile": {
    • "displayName": "West Coast users",
    • "description": "All users West of The Rockies"
    }
}

Retrieve an identity source group
OAuth 2.0 scopes:
  • okta.identitySources.read

Retrieves a group from an identity source for a given identity source ID and group ID or external ID

Request
path Parameters
identitySourceId
required
string

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

Example: 0oa3l6l6WK6h0R0QW0g4
groupOrExternalId
required
string

The Okta group ID or external ID of the identity source group

Example: 00gsl4xM9ys8TdnbZ0g4 or GROUPEXT123456784C2IF
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/identity-sources/{identitySourceId}/groups/{groupOrExternalId}
Request samples 
Response samples 
application/json
{
  • "id": "00gsl4xM9ys8TdnbZ0g4",
  • "externalId": "GROUPEXT123456784C2IF",
  • "profile": {
    • "displayName": "West Coast users",
    • "description": "All users West of The Rockies"
    }
}
Update an identity source group
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Updates a group to an identity source for the given identity source instance and group ID


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


 
 Example:  0oa3l6l6WK6h0R0QW0g4
groupOrExternalId
required
string
The Okta group ID or external ID of the identity source group


 
 Example:  00gsl4xM9ys8TdnbZ0g4 or GROUPEXT123456784C2IF
Request Body schema: application/json
externalId
string  <= 255 characters 
The external ID of the identity source group to be created


 
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.




 
description
string or null  <= 1024 characters 
Description of the group


 
displayName
string  [ 1 .. 255 ] characters 
Name of the group


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/groups/{groupOrExternalId}
Request samples 
application/json
{
  • "externalId": "GROUPEXT123456784C2IF",
  • "profile": {
    • "displayName": "West Coast users",
    • "description": "All users West of The Rockies"
    }
}
Response samples 
application/json
{
  • "id": "00gsl4xM9ys8TdnbZ0g4",
  • "externalId": "GROUPEXT123456784C2IF",
  • "profile": {
    • "displayName": "West Coast users",
    • "description": "All users West of The Rockies"
    }
}
Delete an identity source group
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Deletes a group in an identity source for a given identity source ID and group ID


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


 
 Example:  0oa3l6l6WK6h0R0QW0g4
groupOrExternalId
required
string
The Okta group ID or external ID of the identity source group


 
 Example:  00gsl4xM9ys8TdnbZ0g4 or GROUPEXT123456784C2IF
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/identity-sources/{identitySourceId}/groups/{groupOrExternalId}
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": [ ]
}
Retrieve the memberships for the given identity source group
OAuth 2.0 scopes: 
  • okta.identitySources.read
Retrieves the group memberships for the given identity source group in 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
groupOrExternalId
required
string
The Okta group ID or external ID of the identity source group


 
 Example:  00gsl4xM9ys8TdnbZ0g4 or GROUPEXT123456784C2IF
query Parameters
after
string
The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination and Link header.


 
limit
integer <int32>   <= 1000 
Specifies the number of group membership results in a page. Okta recommends using a specific value other than the default or maximum.
If your request times out, retry your request with a smaller limit and page the results.


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/identity-sources/{identitySourceId}/groups/{groupOrExternalId}/membership
Request samples 
Response samples 
application/json
{
  • "memberExternalIds": [
    • "USEREXT123456784C2IFA",
    • "USEREXT123456784C3IFB",
    • "USEREXT123456784C4IFC"
    ]
}
Create the memberships for the given identity source group
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Creates the group memberships for the given identity source group


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


 
 Example:  0oa3l6l6WK6h0R0QW0g4
groupOrExternalId
required
string
The Okta group ID or external ID of the identity source group


 
 Example:  00gsl4xM9ys8TdnbZ0g4 or GROUPEXT123456784C2IF
Request Body schema: application/json
memberExternalId
string  <= 255 characters 
The external ID of the user to be added as a member of the group in Okta


 
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/groups/{groupOrExternalId}/membership
Request samples 
application/json
{
  • "memberExternalId": "USEREXT123456784C2IFA"
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Delete the memberships for the specified identity source group
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Deletes group memberships for the specified identity source group using member external IDs


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


 
 Example:  0oa3l6l6WK6h0R0QW0g4
groupOrExternalId
required
string
The Okta group ID or external ID of the identity source group


 
 Example:  00gsl4xM9ys8TdnbZ0g4 or GROUPEXT123456784C2IF
memberExternalId
required
string
The external ID of the identity source user


 
 Example:  USEREXT123456784C2IFA
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/identity-sources/{identitySourceId}/groups/{groupOrExternalId}/membership/{memberExternalId}
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": [ ]
}
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
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
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
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
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"
    }
]
Create an identity source user
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Creates a user in an identity source 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
Request Body schema: application/json
externalId
string  <= 512 characters 
The external ID of the user in the identity source


 
object (IdentitySourceUserProfileForUpsertRequired) 
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.




 
email
required
string <email>   [ 5 .. 100 ] characters 
Email address of the user


 
userName
required
string  <= 100 characters 
Username of the user


 
firstName
string or null  [ 1 .. 50 ] characters 
First name of the user


 
homeAddress
string or null  <= 4096 characters 
Home address of the user


 
lastName
string or null  [ 1 .. 50 ] characters 
Last name of the user


 
mobilePhone
string or null  <= 100 characters 
Mobile phone number of the user


 
secondEmail
string <email>   [ 5 .. 100 ] characters 
Alternative email address of the user


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/identity-sources/{identitySourceId}/users
Request samples 
application/json
{
  • "externalId": "EXT987654321Z9Y7X",
  • "profile": {
    • "userName": "emily.jones@example.com",
    • "firstName": "Emily",
    • "lastName": "Jones",
    • "email": "emily.jones@example.com",
    • "secondEmail": "emily.secondary@example.com",
    • "mobilePhone": "987-654-3210",
    • "homeAddress": "10800 NE 8th St #600, Bellevue, WA 98004"
    }
}
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Retrieve an identity source user
OAuth 2.0 scopes: 
  • okta.identitySources.read
Retrieves a user by external ID in an identity source 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
externalId
required
string
The external ID of the user


 
 Example:  00u7m9p9ZT8k2S2EX1f7
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/identity-sources/{identitySourceId}/users/{externalId}
Request samples 
Response samples 
application/json
{
  • "id": "00u7m9p9ZT8k2S2EX1f7",
  • "externalId": "EXT987654321Z9Y7X",
  • "created": "2025-07-24T12:06:05.000Z",
  • "lastUpdated": "2025-08-05T16:15:44.000Z",
  • "profile": {
    • "userName": "emily.jones@example.com",
    • "firstName": "Emily",
    • "lastName": "Jones",
    • "email": "emily.jones@example.com",
    • "secondEmail": "emily.secondary@example.com",
    • "mobilePhone": "987-654-3210",
    • "homeAddress": "10800 NE 8th St #600, Bellevue, WA 98004"
    }
}
Replace an existing identity source user
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Replaces an existing user for the given identity source instance and external ID


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


 
 Example:  0oa3l6l6WK6h0R0QW0g4
externalId
required
string
The external ID of the user


 
 Example:  00u7m9p9ZT8k2S2EX1f7
Request Body schema: application/json
externalId
string  <= 512 characters 
The external ID of the user in the identity source


 
object (IdentitySourceUserProfileForUpsertRequired) 
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.




 
email
required
string <email>   [ 5 .. 100 ] characters 
Email address of the user


 
userName
required
string  <= 100 characters 
Username of the user


 
firstName
string or null  [ 1 .. 50 ] characters 
First name of the user


 
homeAddress
string or null  <= 4096 characters 
Home address of the user


 
lastName
string or null  [ 1 .. 50 ] characters 
Last name of the user


 
mobilePhone
string or null  <= 100 characters 
Mobile phone number of the user


 
secondEmail
string <email>   [ 5 .. 100 ] characters 
Alternative email address of the user


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/identity-sources/{identitySourceId}/users/{externalId}
Request samples 
application/json
{
  • "profile": {
    • "firstName": "Emily",
    • "lastName": "Brock",
    • "email": "brockly@email.com",
    • "userName": "brockly@email.com"
    }
}
Response samples 
application/json
{
  • "profile": {
    • "firstName": "Emily",
    • "lastName": "Brock",
    • "email": "brockly@email.com",
    • "userName": "brockly@email.com",
    • "secondEmail": null,
    • "mobilePhone": null,
    • "homeAddress": null
    }
}
Update an identity source user
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Updates a user to an identity source for the given identity source instance and external ID


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


 
 Example:  0oa3l6l6WK6h0R0QW0g4
externalId
required
string
The external ID of the user


 
 Example:  00u7m9p9ZT8k2S2EX1f7
Request Body schema: application/json
object (IdentitySourceUserProfileForUpsertRequired) 
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.




 
email
required
string <email>   [ 5 .. 100 ] characters 
Email address of the user


 
userName
required
string  <= 100 characters 
Username of the user


 
firstName
string or null  [ 1 .. 50 ] characters 
First name of the user


 
homeAddress
string or null  <= 4096 characters 
Home address of the user


 
lastName
string or null  [ 1 .. 50 ] characters 
Last name of the user


 
mobilePhone
string or null  <= 100 characters 
Mobile phone number of the user


 
secondEmail
string <email>   [ 5 .. 100 ] characters 
Alternative email address of the user


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


patch/api/v1/identity-sources/{identitySourceId}/users/{externalId}
Request samples 
application/json
{
  • "profile": {
    • "firstName": "Emily",
    • "lastName": "Brock",
    • "email": "emily.brock@update.com",
    • "userName": "emily.brock@update.com"
    }
}
Response samples 
application/json
{
  • "profile": {
    • "firstName": "Emily",
    • "lastName": "Brock",
    • "email": "emily.brock@update.com",
    • "userName": "emily.brock@update.com",
    • "secondEmail": "emily.secondary@example.com",
    • "mobilePhone": "987-654-3210",
    • "homeAddress": "10800 NE 8th St #600, Bellevue, WA 98004"
    }
}
Delete an identity source user
OAuth 2.0 scopes: 
  • okta.identitySources.manage
Deletes a user in an identity source for the given identity source instance and external ID


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


 
 Example:  0oa3l6l6WK6h0R0QW0g4
externalId
required
string
The external ID of the user


 
 Example:  00u7m9p9ZT8k2S2EX1f7
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/identity-sources/{identitySourceId}/users/{externalId}
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": [ ]
}