Skip to main content
GET
Typescript (SDK)

Search syntax

A search query is made up of one or more conditions in the format <fieldName><operator><value>. Conditions can be combined with the AND and OR logical operators and grouped with parentheses ().Examples:
  • clientName=internal-client
  • clientIdAlias:client-123 OR clientName:name
  • (clientIdAlias:client OR clientIdAlias:internal) AND clientName:my-prefix
Values that contain white space must be quoted, e.g. clientName="my client name". Full URI values used with the = operator must also be quoted, e.g. entityId="https://entity-id.example.com".

Searchable fields

Limits

  • The length of the q parameter is limited to 200 characters by default.
  • A single search can paginate through at most 1,000 clients by default. Once this limit is reached, nextCursor is no longer returned. To iterate through more clients than this, use the /api/&#123;serviceId&#125;/client API and filter the results on the client side.

Authorizations

Authorization
string
header
required

Authenticate every request with a Service Access Token or Organization Token. Set the token value in the Authorization: Bearer <token> header.

Service Access Token: Scoped to a single service. Use when automating service-level configuration or runtime flows.

Organization Token: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically.

Both token types are issued by the Authlete console or provisioning APIs.

Path Parameters

serviceId
string
required

The ID of the service to retrieve a list of clients from.

Pattern: ^\d+$

Query Parameters

q
string

The search query. See the description of this API for the supported syntax and fields.

This parameter is required unless cursor is provided. When cursor is provided, this parameter is ignored and the search query stored in the cursor is used instead.

cursor
string

This should be set to the value of nextCursor from a previous call to this endpoint, which will retrieve the next set of clients matching the original search query. If this is not provided the search will start from the beginning.

limit
integer<int32>

The maximum amount of results to return from this request. This value will be clamped between 1 and the allowed maximum. The default will be used if no value is provided.

includeTotalCount
boolean

Indicates whether the totalCount property should be calculated and included in the response, otherwise it will be unset.

Warning: Calculating the total count requires an additional query and reduces the performance and throughput of this API. Only set this to true when the total count is actually required, rather than on every request.

Response

limit
integer<int32>

The clamped requested limit of clients to return from the request.

nextCursor
string

If there are more matching entries to retrieve this value will be generated and returned. The next call to this endpoint should use this value as the cursor to continue to retrieve the remaining clients from the correct point. If there are no further matching clients, or the search pagination limit has been reached, this property will not be set.

totalCount
integer<int32>

The total number of clients in the service that match the search query. This doesn't mean the number of clients contained in the response. Only set when includeTotalCount is true in the request.

entities
object[]

The list of clients matching the search query.