# Subject Search API {#subject-search-api}

The Subject Search API defines the message exchange pattern between a client (PEP) and an authorization service (PDP) for returning all of the subjects that match the search criteria.

The Subject Search API is based on the Access Evaluation API, but omits the Subject ID.

## The Subject Search API Request {#subject-search-request}
The Subject Search request is a 3-tuple constructed of three previously defined entities:

`subject`:
: REQUIRED. The subject (or principal) of type Subject. NOTE that the Subject type is REQUIRED but the Subject ID can be omitted, and if present, is IGNORED.

`action`:
: REQUIRED. The action (or verb) of type Action.

`resource`:
: REQUIRED. The resource of type Resource.

`page`:
: OPTIONAL. A page token for paged requests.

### Example (non-normative)

The following payload defines a request for the subjects of type `user` that can perform the `can_read` action on the resource of type `account` and ID `123`.

~~~ json
{
"subject": {
"type": "user"
},
"action": {
"name": "can_read",
},
"resource": {
"type": "account",
"id": "123"
}
}
~~~
{: #subject-search-request-example title="Example Request"}

## The Subject Search API Response {#subject-search-response}

The response is a paged array of Subjects.

~~~ json
{
"results": [
{
"type": "user",
"id": "[e-mail]"
},
{
"type": "user",
"id": "[e-mail]"
}
],
"page": {
"next_token": ""
}
}
~~~

### Paged requests

A response that needs to be split across page boundaries returns a non-empty `page.next_token`.

#### Example

~~~ json
{
"results": [
{
"type": "user",
"id": "[e-mail]"
},
{
"type": "user",
"id": "[e-mail]"
}
],
"page": {
"next_token": "alsehrq3495u8"
}
}
~~~

To retrieve the next page, provide `page.next_token` in the next request:

~~~ json
{
"subject": {
"type": "user"
},
"action": {
"name": "can_read",
},
"resource": {
"type": "account",
"id": "123"
},
"page": {
"next_token": "alsehrq3495u8"
}
}
~~~

Note: page size is implementation-dependent.

# Resource Search API {#resource-search-api}

The Resource Search API defines the message exchange pattern between a client (PEP) and an authorization service (PDP) for returning all of the resources that match the search criteria.

The Resource Search API is based on the Access Evaluation API, but omits the Resource ID.

## The Resource Search API Request {#resource-search-request}
The Resource Search request is a 3-tuple constructed of three previously defined entities:

`subject`:
: REQUIRED. The subject (or principal) of type Subject.

`action`:
: REQUIRED. The action (or verb) of type Action.

`resource`:
: REQUIRED. The resource of type Resource. NOTE that the Resource type is REQUIRED but the Resource ID can be omitted, and if present, is IGNORED.

`page`:
: OPTIONAL. A page token for paged requests.

### Example (non-normative)

The following payload defines a request for the resources of type `account` on which the subject of type `user` and ID `[e-mail]` can perform the `can_read` action.

~~~ json
{
"subject": {
"type": "user",
"id": "[e-mail]"
},
"action": {
"name": "can_read",
},
"resource": {
"type": "account"
}
}
~~~
{: #resource-search-request-example title="Example Request"}

## The Resource Search API Response {#resource-search-response}

The response is a paged array of Resources.

~~~ json
{
"results": [
{
"type": "account",
"id": "123"
},
{
"type": "account",
"id": "456"
}
],
"page": {
"next_token": ""
}
}
~~~

### Paged requests

A response that needs to be split across page boundaries returns a non-empty `page.next_token`.

#### Example

~~~ json
{
"results": [
{
"type": "account",
"id": "123"
},
{
"type": "account",
"id": "456"
}
],
"page": {
"next_token": "alsehrq3495u8"
}
}
~~~

To retrieve the next page, provide `page.next_token` in the next request:

~~~ json
{
"subject": {
"type": "user",
"id": "[e-mail]"
},
"action": {
"name": "can_read",
},
"resource": {
"type": "account"
},
"page": {
"next_token": "alsehrq3495u8"
}
}
~~~

Note: page size is implementation-dependent.