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
Name	Value
`Authorization`	`Bearer <EOSAccessToken>`
`Content-Type`	`application/json`
Path Parameters
Name	Type	Description	Required
`ProductUserId`	String	The EOS `ProductUserId` to query sanctions for	Yes
Query Parameters
Name	Type	Description	Required
`action`	String	Optional `action` filter. Supports multiple values: `action=action1&action=action2`. Max items: 5.	No

Example Request

Response

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

CompactSanction

CompactSanction
Name	Type	Description
`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

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

SanctionEvent
Name	Type	Description
`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
Name	Type	Description
...	...	Metadata key/value pairs. Max item count: 25. Item key max length: 64. Item value max length: 128.

SanctionModification

SanctionModification
Name	Type	Description
`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

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

CompactSanctionWithPuid
Name	Type	Description
`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

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

SanctionPostPayload

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

Sanction
Name	Type	Description
`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

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

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

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

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

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

SanctionPatchPayload

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

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

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

SanctionDeletePayload

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 - No Content.

Paging

Paging
Name	Type	Description
`offset`	Integer	The pagination offset
`limit`	Integer	The sanctions count returned per call
`total`	Integer	The total sanctions count

Creating Sanction Appeals

Policy

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

Authorization

This call requires Bearer Token authorization with an EOS Client Auth access token.

Request

HTTP Request	`POST /sanctions/v1/{deploymentId}/appeals`
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
`AppealPostPayload`	The sanction appeal payload

Example Request

AppealPostPayload

AppealPostPayload
Name	Type	Description	Required
`referenceId`	String	Unique identifier for the sanction being appealed.	Yes
`reason`	Integer	The reason code for the appeal. `1`: Incorrect sanction. `2`: Compromised account. `3`: Unfair punishment. `4`: Appeal for forgiveness.	Yes

Response

HTTP Response 200 - OK: Success.
HTTP Headers
Name		Value
`Content-Type`		`application/json`
JSON Payload
Type	Description
Appeal	The appeal created

Appeal

Appeal
Name	Type	Description
`id`	String	Unique identifier for the appeal
`status`	String	The status of the appeal
`referenceId`	String	Unique identifier for the sanction being appealed
`createdAt`	String	Time when this appeal request was created. Time defined in ISO 8601 and RFC3339, for example: `2021-01-01T00:00:00.000Z`
`updatedAt`	String	Time when this appeal was updated. Time defined in ISO 8601 and RFC3339, for example: `2021-01-01T00:00:00.000Z`
`reason`	Integer	The reason code of the appeal.

Example Response

Querying Sanction Appeals

Policy

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

Authorization

This call requires Bearer Token authorization with an EOS Client Auth access token.

Request

HTTP Request	`GET /sanctions/v1/{deploymentId}/appeals`
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
`referenceId`	String	The sanction identifier filter. Multiple allowed.	No
`status`	String	The appeal status filter. Multiple allowed.	No
`productUserId`	String	The product user id filter. Multiple allowed.	No

Example Request

Response

HTTP Response 200 - OK: Success.
HTTP Headers
Name		Value
`Content-Type`		`application/json`
JSON Payload
Name	Type	Description
`elements`	Array<Appeal>	List of appeals ordered by createdAt descending.
`paging`	Object<Paging>	Pagination information