Request Parameters Response Elements Errors Examples See Also

SearchPrincipals

Searches Identity Center for users and groups in a domain. The domain must be configured with Identity Center.

To grant access to a result, pass its principalId to CreateAccessGrant with a principalType of IDC_USER for a user or IDC_GROUP for a group.

Request Parameters

domainId

The ID of the domain to search within.

Type: String

Pattern: d-[0-9a-z]{1,25}

Required: Yes

maxResults

The maximum number of results to return. Defaults to 10. Valid only when searchQuery is *; other searches reject this parameter and return at most 10 results.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 50.

Required: No

nextToken

A token to retrieve the next page of results. Valid only when searchQuery is *; other searches do not paginate and reject this parameter. Tokens expire after 24 hours.

Type: String

Required: No

searchQuery

A search term to match against user names, display names, and IDs. Pass * to list all principals. Maximum 128 characters.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: Yes

Response Elements

The following elements are returned by the service.

nextToken

A token to retrieve the next page of results, or null if there are no more results.

Type: String

results

The list of matching principals.

Type: Array of PrincipalSearchResult objects

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

The caller is not authorized to perform this action.

HTTP Status Code: 403

InternalServerException

An unexpected error occurred while processing the request.

errorCode: The error code associated with the internal error.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

errorCode: The error code associated with the failure.
resourceId: The identifier of the resource that could not be found. Not always present.
resourceType: The type of the resource that could not be found. Not always present.

HTTP Status Code: 404

ThrottlingException

The request was throttled due to exceeding the allowed request rate.

retryAfterSeconds: The number of seconds to wait before retrying the request. Not always present.

HTTP Status Code: 429

ValidationException

A parameter is specified incorrectly.

errorCode: The error code associated with the validation failure.

HTTP Status Code: 400

Examples

Search principals by name

The following example searches a domain for principals whose name matches a text query. A text search (any searchQuery other than *) returns at most 10 results and does not paginate, so maxResults and nextToken are not supplied and no nextToken is returned. To grant access to a result, pass its principalId to CreateAccessGrant with a principalType of IDC_USER for a user or IDC_GROUP for a group. Payloads are shown as JSON; on the wire they are CBOR-encoded.

Sample Request


{
  "domainId": "d-1a2b3c4d5e",
  "searchQuery": "jane"
}

Sample Response


{
  "results": [
    {
      "displayName": "Jane Doe",
      "principalId": "94b6c7d8-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "principalType": "USER",
      "userName": "jane.doe"
    },
    {
      "displayName": "Jane's Analysts",
      "principalId": "2f5a8c1b-6d3e-4f7a-8b9c-0d1e2f3a4b5c",
      "principalType": "GROUP"
    }
  ]
}