Sanctions Web APIs

Use the Sanctions Web APIs to use Sanctions interface features with RESTful services.

20 mins to read

The Epic Online Services (EOS) Sanctions interface manages punitive actions taken against your users. Actions may include temporary or permanent bans from gameplay, communications, or others that limit the social aspects of your product for a particular user. You define the disciplinary actions for your product to handle negative behavior based on your use cases.

You can use the Sanctions Web APIs to supplement the EOS C SDK for trusted server applications. Before calling the Sanctions Web APIs, check out the Web API Overview for standards, authentication, and error codes.

Sanctions Web API Endpoint

https://api.epicgames.dev/sanctions/

Querying Active Sanctions for a Specific Player

Policy

The client policy used must have the sanctions:findActiveSanctionsForAnyUser action allowed.

Authorization

This call requires Bearer Token authorization with an EOS Client Auth access token, obtained from the Connect interface.

Request

HTTP Request GET /sanctions/v1/productUser/{ProductUserId}/active
HTTP Headers
NameValue
Authorization Bearer <EOSAccessToken>
Content-Type application/json
Path Parameters
NameTypeDescriptionRequired
ProductUserId String The EOS ProductUserId to query sanctions for Yes
Query Parameters
NameTypeDescriptionRequired
action String

Optional action filter. Supports multiple values: action=action1&action=action2. Max items: 5.

No

Example Request

curl "https://api.epicgames.dev/sanctions/v1/productUser/<ProductUserId>/active" \
-H "accept: application/json" \
-H "Authorization: Bearer <EOSAccessToken>"

Response

HTTP Response 200 - OK: Success.
HTTP Headers
NameValue
Content-Type application/json
JSON Payload
NameTypeDescription
elements Array<CompactSanction> List of active sanctions

CompactSanction

CompactSanction
NameTypeDescription
referenceId String Unique identifier for this sanction
timestamp int64 Epoch timestamp in seconds when this sanction was placed
action String Action string associated with this sanction
expirationTimestamp int64 Epoch timestamp in seconds when this expiration expires, or null if the sanction is permanent

Synchronizing Sanctions to an External Service

Policy

The client policy used must have the Sanctions:syncSanctionEvents action allowed.

Authorization

This call requires Bearer Token authorization with an EOS Client Auth access token, obtained from the Connect interface.

Request

HTTP Request GET /sanctions/v1/sync
HTTP Headers
NameValue
Authorization Bearer <EOSAccessToken>
Content-Type application/json
Query Parameters
NameTypeDescriptionRequired
lastLogId String Optional ID of the last sanction event entry processed in the previous call. No

Example Request

curl "https://api.epicgames.dev/sanctions/v1/sync" \
-H "accept: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
-G \
-d lastLogId=<LastLogId>

Response

HTTP Response 200 - OK: Success.
HTTP Headers
NameValue
Content-Type application/json
JSON Payload
NameTypeDescription
elements Array<SanctionEvent> List of sanction events

SanctionEvent

SanctionEvent
NameTypeDescription
productUserId String Sanctioned user’s EOS ProductUserId
action String Action string associated with this sanction
justification String Justification string associated with this sanction
source String Source which created this sanction, e.g. ‘developer-portal’
eventType Integer 1: Sanction was created 2: Sanction was updated 3: Sanction was deleted
tags Array<String> List of tags associated with this sanction
logId String

Unique identifier for a SanctionEvent log entry. This value can be used to request incremental updates from the sync API.

referenceId String Unique identifier for this sanction
timestamp String Time when this sanction event happened
expirationTimestamp String Time when this expiration expires, or null if the sanction is permanent
batchUuid String UUID for the request associated with this sanction. One request may create multiple sanctions as a batch.
epicAccountName String Name of the Epic Games account that placed this sanction
epicAccountId String ID of the Epic Games account that placed this sanction
eosClientId String Client credential ID which was used to place this sanction
eosClientRole String Role of the client credential which was used to place this sanction
createdAt String Time when this sanction request was received by the Sanctions service backend
updatedAt String Time when this sanction was updated
trustedPartner String The trusted partner that placed this sanction on behalf of the developer
deploymentId String EOS DeploymentId that this sanction applies to
pending Boolean True if this sanction is currently pending
automated Boolean True if this sanction was created by any method other than manual action in the developer portal website
metadata SanctionMetadata Arbitrary metadata key/value pairs associated with this sanction
displayName String Display name of sanctioned user
identityProvider String Identity provider that the sanctioned user authenticated with
accountId String Sanctioned user’s account ID with the specified identityProvider
modifications SanctionModification List of modifications associated with a sanction update. This field is only set when eventType is 2.

SanctionMetadata

SanctionMetadata
NameTypeDescription
... ... Metadata key/value pairs. Max item count: 25. Item key max length: 64. Item value max length: 128.

SanctionModification

SanctionModification
NameTypeDescription
updated_at String Time when this modification was made
... ... Additional key/value pairs from SanctionEvent indicating what was changed in the update

Bulk Querying Active Sanctions for Multiple Players

Policy

The client policy used must have one of the following actions allowed:

  • sanctions:findActiveSanctionsForAnyUser
  • sanctions:findSanctionsForAnyUser
  • sanctions:findAllSanctions
  • sanctions:syncSanctionEvents

Authorization

This call requires Bearer Token authorization with an EOS Client Auth access token, obtained from the Connect interface.

Request

HTTP Request GET /sanctions/v1/{deploymentId}/active-sanctions
HTTP Headers
NameValue
Authorization Bearer <EOSAccessToken>
Content-Type application/json
Path Parameters
NameTypeDescriptionRequired
deploymentId String The deploymentId to query for Yes
Query Parameters
NameTypeDescriptionRequired
productUserId String

Required product user ID filter. Supports multiple values: productUserId=productUserId1&productUserId=productUserId2 Max items: 100

Yes
action String Required action filter. Supports multiple values: action=action1&action=action2 Max items: 5 Yes

Example Request

curl "https://api.epicgames.dev/sanctions/v1/deploymentId1/active-sanctions?productUserId=productUserId1&productUserId=productUserId2&action=action1&action=action2" \
-H "accept: application/json" \
-H "Authorization: Bearer <EOSAccessToken>"

Response

HTTP Response 200 - OK: Success.
HTTP Headers
NameValue
Content-Type application/json
JSON Payload
NameTypeDescription
elements Array<CompactSanctionWithPuid> List of active sanctions

CompactSanctionWithPuid

CompactSanctionWithPuid
NameTypeDescription
productUserId String The product user ID
referenceId String Unique identifier for this sanction
timestamp String Time when this sanction was placed in ISO 8601 format
action String Action string associated with this sanction
expirationTimestamp String Time when this expiration expires in ISO 8601, or null if the sanction is permanent

Example Response

{
"elements": [
{
"productUserId": "productUserId1",
"referenceId": "example_reference_id_1",
"timestamp": "2020-04-15T13:18:25.431762Z",
"action": "action1",
"expirationTimestamp": null
},
{
"productUserId": "productUserId2",
"referenceId": "example_reference_id_2",
"timestamp": "2020-04-15T13:32:44.261711Z",
"action": "action2",
"expirationTimestamp": null
}
]
}

Creating Sanctions

Policy

The client policy used must have the sanctions:createSanction action allowed.

Authorization

This call requires Bearer Token authorization with an EOS Client Auth access token, obtained from the Connect interface.

Request

HTTP Request POST /sanctions/v1/{deploymentId}/sanctions
HTTP Headers
NameValue
Authorization Bearer <EOSAccessToken>
Content-Type application/json
Path Parameters
NameTypeDescriptionRequired
deploymentId String The deploymentId to query for Yes
JSON Payload
TypeDescription
Array<SanctionPostPayload> List of sanctions to create

Example Request

curl --request POST "https://api.epicgames.dev/sanctions/v1/deploymentId1/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
--data-raw '[
{
"action": "EXAMPLE_ACTION",
"duration": 0,
"justification": "example_justification",
"source": "example_source",
"productUserId": "example_product_user_id",
"pending": false,
"automated": true,
"tags": ["example_tag_1", "example_tag_2"],
"metadata": {
"example_metadata_1":"meta_1",
"example_metadata_2":"meta_2"
},
"displayName": "example_display_name",
"identityProvider": "example_identity_provider",
"accountId": "example_account_id"
}
]

SanctionPostPayload

SanctionPostPayload
NameTypeDescriptionRequired
productUserId String Sanctioned user’s EOS ProductUserId Yes
action String Action string associated with this sanction. Format: [a-zA-Z0-9_-]+. Min length: 1. Max length: 64. Yes
justification String Justification string associated with this sanction. Min length: 1 Max length: 2048 Yes
source String

Source which created this sanction, e.g. ‘developer-portal’. Format: [a-zA-Z0-9_-]+. Min length: 2. Max length: 64.

Yes
tags Array<String>

List of tags associated with this sanction. Items are case insensitive and unique. Item format: [a-zA-Z0-9_-]+. Item max length: 16

No
pending Boolean True if this sanction is currently pending No
metadata SanctionMetadata Arbitrary metadata key/value pairs associated with this sanction No
displayName String Display name of sanctioned user. Max length: 64 No
identityProvider String Identity provider that the sanctioned user authenticated with. Max length: 64 No
accountId String Sanctioned user’s account ID with the specified identityProvider. Max length: 64 No
duration integer The length of the sanction in seconds No

Response

HTTP Response 200 - OK: Success.
HTTP Headers
NameValue
Content-Type application/json
JSON Payload
NameTypeDescription
elements Array<Sanction> List of sanctions created

Sanction

Sanction
NameTypeDescription
productUserId String Sanctioned user’s EOS ProductUserId
action String Action string associated with this sanction
justification String Justification string associated with this sanction
source String Source which created this sanction, e.g. ‘developer-portal’
tags Array<String> List of tags associated with this sanction
referenceId String Unique identifier for this sanction
timestamp String Time when this sanction was placed.
expirationTimestamp String Time when this expiration expires, or null if the sanction is permanent
batchUuid String UUID for the request associated with this sanction. One request may create multiple sanctions as a batch.
epicAccountName String Name of the Epic Games account that placed this sanction
epicAccountId String ID of the Epic Games account that placed this sanction
eosClientId String Client credential ID which was used to place this sanction
eosClientRole String Role of the client credential which was used to place this sanction
createdAt String Time when this sanction request was received by the Sanctions service backend. Time defined in ISO 8601 and RFC3339, for example: 2021-01-01T00:00:00.000Z.
updatedAt String Time when this sanction was updates. Time defined in ISO 8601 and RFC3339, for example: 2021-01-01T00:00:00.000Z.
removedAt String Time when this sanction was removed. Time defined in ISO 8601 and RFC3339, for example: 2021-01-01T00:00:00.000Z.
trustedPartner String The trusted partner that placed this sanction on behalf of the developer
deploymentId String EOS DeploymentId that this sanction applies to
pending Boolean True if this sanction is currently pending
automated Boolean True if this sanction was created by any method other than manual action in the developer portal website
metadata SanctionMetadata Arbitrary metadata key/value pairs associated with this sanction
displayName String Display name of sanctioned user
identityProvider String Identity provider that the sanctioned user authenticated with
accountId String Sanctioned user’s account ID with the specified identityProvider
status String The status of this sanction. Including Active, Pending, Expired, Removed

Note: Time is defined in ISO 8601 and RFC3339. For example: 2021-01-01T00:00:00.000Z.

Example Response

{
"elements": [
{
"referenceId": "7cd6de84-b5be-405a-8fa1-55c11c821a1e",
"timestamp": "2022-03-02T19:54:42.402355Z",
"expirationTimestamp": null,
"batchUuid": "645eba40-dd53-4cea-95d3-3e22459bb84d",
"epicAccountName": null,
"epicAccountId": "",
"eosClientId": "example_client_id",
"eosClientRole": "",
"createdAt": "2022-03-02T19:54:42.402243Z",
"updatedAt": null,
"trustedPartner": null,
"metadata": {
"example_metadata_1": "meta_1",
"example_metadata_2": "meta_2"
},
"deploymentId": "deploymentId1",
"productUserId": "example_product_user_id",
"pending": false,
"automated": true,
"source": "example_source",
"justification": "example_justification",
"tags": ["example_tag_1", "example_tag_2"],
"action": "EXAMPLE_ACTION",
"displayName": "example_display_name",
"identityProvider": "example_identity_provider",
"accountId": "example_account_id",
"status": "Active"
}
]
}

Querying All Sanctions

Policy

The client policy used must have one of the following actions allowed:

  • sanctions:findSanctionsForAnyUser
  • sanctions:findAllSanctions
  • sanctions:syncSanctionEvents

Authorization

This call requires Bearer Token authorization with an EOS Client Auth access token, obtained from the Connect interface.

Request

HTTP Request GET /sanctions/v1/{deploymentId}/sanctions
HTTP Headers
NameValue
Authorization Bearer <EOSAccessToken>
Content-Type application/json
Path Parameters
NameTypeDescriptionRequired
deploymentId String The deploymentId to query for Yes
Query Parameters
NameTypeDescriptionRequired
limit integer The number of elements to return. Default 100. No
offset integer The number of elements to skip. Default 0. No

Example Request

curl --request GET "https://api.epicgames.dev/sanctions/v1/deploymentId1/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>"

Response