Sanctions Web APIs

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

Contents

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.

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

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Path Parameters

Name

Type

Descriptions

Required

ProductUserId

String

The EOS ProductUserId to query sanctions for

Yes

Query Parameters

Name

Type

Descriptions

Required

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

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array

List of active sanctions

CompactSanction

CompactSanction

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

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Query Parameters

Name

Type

Description

Required

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

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array<SanctionEvent>

List of sanction events

SanctionEvent

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 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

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

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

SanctionModification

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

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Path Parameters

Name

Type

Description

Required

deploymentId

String

The deploymentId to query for

Yes

Query Parameters

Name

Type

Description

Required

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

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array<CompactSanctionWithPuid>

List of active sanctions

CompactSanctionWithPuid

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 format, 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

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Path Parameters

Name

Type

Description

Required

deploymentId

String

The deploymentId to query for

Yes

JSON Payload

Type

Description

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

Name

Type

Description

Required

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

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array<Sanction>

List of sanctions created

Sanction

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.

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

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

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Path Parameters

Name

Type

Description

Required

deploymentId

String

The deploymentId to query for

Yes

Query Parameters

Name

Type

Description

Required

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

HTTP Response 200 - OK: Success.

HTTP Headers

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array<Sanction>

List of sanctions ordered by createdAt descending.

paging

Object<Paging>

Pagination information

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"
        }
    ],
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 100
    }
}

Querying All Sanctions for a player

Policy

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

  • sanctions:findSanctionsForAnyUser

  • sanctions:findSanctionsForLocalUser

  • 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}/users/{productUserId}

HTTP Headers

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Path Parameters

Name

Type

Description

Required

deploymentId

String

The deploymentId to query for

Yes

productUserId

String

The productUserId to query for

Yes

Query Parameters

Name

Type

Description

Required

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/users/example_product_user_id" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" 

Response

HTTP Response 200 - OK: Success.

HTTP Headers

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array<Sanction>

List of sanctions ordered by createdAt descending.

paging

Object<Paging>

Pagination information

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"
        }
    ],
    "paging": {
        "total": 1,
        "offset": 0,
        "limit": 100
    }
}

Updating Sanctions

Policy

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

Authorization

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

Request

HTTP Request

PATCH /sanctions/v1/{deploymentId}/sanctions

HTTP Headers

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Path Parameters

Name

Type

Description

Required

deploymentId

String

The deploymentId to query for

Yes

JSON Payload

Type

Description

Array<SanctionPatchPayload>

List of sanctions update to apply

Example Request

curl --request PATCH "https://api.epicgames.dev/sanctions/v1/deploymentId1/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
--data-raw '[{
    "referenceId": "7cd6de84-b5be-405a-8fa1-55c11c821a1e",
    "updates" : {
        "tags": ["updated_example_tag_1","updated_example_tag_2"],
        "justification": "updated_example_justification",
        "metadata": {
            "updated_example_metadata_1":"updated_example_metadata_1",
            "updated_example_metadata_2":"updated_example_metadata_2"
        }
    }
}]'

SanctionPatchPayload

Name

Type

Description

Required

referenceId

String

Unique identifier for this sanction

Yes

updates

UpdatableFields

Fields to be updated and their new values.

Yes

UpdatableFields

Name

Type

Description

Required

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

metadata

SanctionMetadata

Arbitrary metadata key/value pairs associated with this sanction

No

justification

String

Justification string associated with this sanction. Min length: 1 Max length: 2048

No

Response

HTTP Response 200 - OK: Success.

HTTP Headers

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array<Sanction>

List of sanctions updated

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": "2022-03-02T20:01:12.311744Z",
            "trustedPartner": null,
            "metadata": {
                "updated_example_metadata_1": "updated_example_metadata_1",
                "updated_example_metadata_2": "updated_example_metadata_2"
            },
            "deploymentId": "deploymentId1",
            "productUserId": "example_product_user_id",
            "pending": false,
            "automated": true,
            "source": "example_source",
            "justification": "updated_example_justification",
            "tags": [
                "updated_example_tag_1",
                "updated_example_tag_2"
            ],
            "action": "EXAMPLE_ACTION",
            "displayName": "example_display_name",
            "identityProvider": "example_identity_provider",
            "accountId": "example_account_id",
            "status": "Active"
        }
    ]
}

Removing Sanctions

Policy

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

Authorization

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

Request

HTTP Request

DELETE /sanctions/v1/{deploymentId}/sanctions

HTTP Headers

Name

Value

Authorization

Bearer <EOSAccessToken>

Content-Type

application/json

Path Parameters

Name

Type

Description

Required

deploymentId

String

The deploymentId to query for

Yes

JSON Payload

Type

Description

SanctionDeletePayload

The sanctions to delete and its justification

Example Request

curl --request DELETE "https://api.epicgames.dev/sanctions/v1/{deploymentId}/sanctions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <EOSAccessToken>" \
--data-raw '{
    "referenceIds": ["7cd6de84-b5be-405a-8fa1-55c11c821a1e"],
    "justification" : "example_delete_justification"`
}

SanctionDeletePayload

Name

Type

Description

Required

referenceIds

Array<String>

Unique identifiers of the sanctions to be removed

Yes

justification

String

Justification string associated with this sanction removal. Min length: 1 Max length: 2048

No

Response

HTTP Response 204 - OK: Success.

HTTP Headers

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

elements

Array<Sanction>

List of sanctions removed

Paging

offset

Integer

The pagination offset

limit

Integer

The sanctions count returned per call

total

Integer

The total sanctions count