> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bespot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server-to-server API

> Server-to-server API integration for verification and policy decisions.

# Server-to-server integration

This page is a reference to all endpoints available for Server-to-server communication.

## Action Verification

Bespot Gatekeeper SDKs when used in customer's frontend applications (Web, Android & iOS) return an `(action, ticket)` tuple as a response. Typically, the policy *action* (evaluation result) would be sufficient for determining if a user is allowed to proceed further. However, there can be potential cases where this information can be tampered with or altered thus bypassing Bespot Gatekeeper's policy action. To ensure that the *action* information is valid, Bespot Gatekeeper API offers a server2server verification mechanism. The client's server collects the policy action `(action, ticket)` from its frontend applications, and then asks Bespot Gatekeeper API to verify it. *Action* information is cross-checked with the accompanied encrypted *ticket* information. *Ticket* information can only be decrypted by the Bespot Gatekeeper API server. If *ticket* or *action* information is tampered with or altered, verification fails. If verification succeeds, the Client's server can then communicate back to its frontend application that *action* information is verified and proceed.

### Resource \[POST]

`[/v2/s2s/verify/]`

### Request

```json theme={null}
{
    "ticket": "string",
    "action": "string",
    "valid_for_at_most_millis": 0,
    "application_package": "string"
}
```

where:

* `ticket` \[string] the encrypted ticket received from the SDK - *Required*
* `action` \[string] the policy action received from the SDK - *Required*
* `valid_for_at_most_millis` \[integer] the period in milliseconds that the action validity will be checked across. If there is no preference, `0` should be set. If `0` or a number `> 3000000` is set, then, it defaults to the system's maximum validity period of 300000 (5 minutes) for security reasons\* - *Required*
* `application_package` \[string] the frontend application's package or bundle identifier (received from Web, Android, iOS) - *Required*

\*For security reasons, we maintain a maximum threshold internally in order to defend against possible malware attacks (e.g. replay attacks).

### Response

<ResponseExample>
  ```json verify theme={null}
  {
      "is_verified": true,
      "action": "string",
      "valid_for_at_most_millis": 0,
      "application_package": "string",
      "action_creation_date": "2024-09-24T06:55:50.089Z",
      "verification_failed_reason": "string"
  }
  ```
</ResponseExample>

where:

* `is_verified` \[boolean] the verification result
* `action` \[string] the policy action received from the SDK. Values:
  * `SAFE` *Everything is normal, no action needed*
  * `MONITOR` *Keep monitoring user session to track any suspicious move*
  * `LIMIT_ACCESS` *Should limit user access, and remove using some crucial features*
  * `BLOCK` *Device should be blocked and immediately stop the application*
* `valid_for_at_most_millis` \[integer] the configured period in milliseconds that the action validity will be checked across
* `application_package` \[string] the frontend application's package or bundle identifier (received from Web, Android, iOS)
* `action_creation_date` \[ISO Date & Time with Timezone] the date and time (with timezone) the action was created in the first place
* `verification_failed_reason`: \[string] a descriptive string explaining the reason verification failed

### Example cURL

```shell theme={null}
curl --location --request POST 'https://antifraud.bespot.dev/v2/s2s/verify/' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API-KEY' \
--data '{
    "ticket": "string",
    "action": "string",
    "valid_for_at_most_millis": 0,
    "application_package": "string"
}'
```

<RequestExample>
  ```bash s2s theme={null}
  curl --location --request POST 'https://antifraud.bespot.dev/v2/s2s/verify/' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: API-KEY' \
  --data '{
      "ticket": "string",
      "action": "string",
      "valid_for_at_most_millis": 0,
      "application_package": "string"
  }'
  ```
</RequestExample>