Skip to main content

Getting started

WARNING: Most of the explanations provided here are tied to the REST API of WellPlayed.
This is due to the fact that the Backoffice is not functional, and will not be updated before WellPlayed v2.
The only usable part of the backoffice is the scoring mechanism.

API Access​

To access the legacy API, you must contact us via this email: [email protected] or through Discord.

Support for the Legacy version will be only provided to Premium customers to Partners.

After contacting us, you will be provided with a client ID and a client secret.
You can either interact with the API using a User Token (by using the Code or Implicit Grant types) or by using the Client Credentials Grant type.

The API documentation is accessible through this link.

The API Endpoint is accessible through https://api.well-played.gg.

The OAuth standard server is accessible here: https://idp.well-played.gg.

Authentication​

If you are not familiar with OAuth 2.0, please take a look to this documentation.

By default, WellPlayed will allow your client to use Client Credentials, Implicit flow (not recommended) or Authorization Code flow.

It is recommended to use either Client Credentials or Authorization Code Flow, depending on your needs.

After the retrieval of the Access token, you must provide this token to all your future requests through the HTTP header Authorization preceded by a Bearer, like the following CURL example: 

curl --header 'Authorization: Bearer ACCESS_TOKEN_HERE' https://api.well-played.gg

Organizations​

Organizations are Tenants equivalents.
Each Events is linked to an Organization and can be managed by members of this Organization depending on their permissions.

Create an organization​

If you want to create an organization, you must contact us first.
After contacting us, you will either be provided directly with an organization linked to your account, or you will be added the permission to create Organizations.

In the second case, you can create your organization using the following endpoint.

Organization permissions and members​

Organizations are ment to provide a simple but advanced way to manage user permissions over the Organization resources.

Add a user to your Organization​

You can provide access to your Organization management resources by adding it to your organization.
This is commonly done by asking the user to connect through the Backoffice, then ask them for their ID, which can be found at the top right of the page:
img.png
Note: the user can click on its ID to copy it

Then, you can use the following endpoint Requires permission: organisation:members:add.

You will need to add your user in a Group. (see bellow)

If you are using a User Grant Flow (Authorization Code or Implicit), you can access the current user permissions through this endpoint.

Create a group​

Groups provide a way to manage shared set of permissions through multiple users.
By setting a user to a specific group, it will inherit the Group's permissions.

To create a group, you can use the following endpoints:

  • List groupsRequires permission: organisation:groups:view
  • CreateRequires permission: organisation:groups:create
  • UpdateRequires permission: organisation:groups:update
Permissions​

The permission system allows for a highly customisable way to provide specific access to users for specific resources, or all resources.
Permissions are defined by a key and a list of resources that defines their limits.
For example, the following permission set:

"permissions": {
  "event:create": [],
  "event:scores:update": ["event:{EVENT_ID}:round:{ROUND_ID}"]
}

Will allow the user to create an event, and to update scores on the Round corresponding to the ID {ROUND_ID} and attached to the event {EVENT_ID}.
By letting the array Empty, the user will have the permission assigned to all resources.

Custom fields​

It is possible to add custom fields to the Organization configuration.
Adding Custom fields is done through the accountCustomFields field in the Organization update endpoint.
These fields are attached to your user Accounts and can be retrieved.
WARNING: You will need to set the fields if they are required when you initialize the user account

Logs​

Logs allows you to follow what happened in your organization.
You can access your logs through this endpoint Requires permission: organisation:logs:view.

Accounts​

Accounts are the main way to identify users through WellPlayed.
There are two type of accounts:

  • The IDP account, which represents the user Identity, it is only used to provide permissions and IDs to the API.
    The ID provided by this IDP is called passportId on the Accounts endpoints and is the primary ID of the account. Further accounts IDs refer to the passportId and not to the Account model idfield.
  • The API account, which contains the user's API related data (username, etc).

Retrieve current user profile​

To retrieve the account of the current user, simply use the following endpoint.
If this endpoint returns a 404 error this means that the user account is not initialized yet, and needs to be initialized.

Initial registration​

To initialize your user, use the following endpoint.
If the Organization has required Custom Fields, you will need to set their value during the initialization process.

Search for accounts​

It is possible to search for specific account by username using the following endpoint.
This is very useful if you want to create a UI to search and invite users to a team.

Account identities​

Account identities are properties linked to an account, to retrieve specific datas from another identity provider.
Only one identity is available right now: Twitch.

Each Account Identity will provide specific properties depending on the IDP that is used to attach them.
Accessing a specific account identities is done through this endpoint.
If you need to access the current user's identities, you can use this endpoint.

Updating an account identity is done through this endpoint.
The endpoint will ask for a X-Identity-Authorization header, which represents an Authorization token generated from the Identity Provider you are targeting.
This method does not require a specific Client ID or Client Secret, you can use your own Client ID

Twitch identity​

The Twitch identity will provide the following properties once linked to an account:

  • id String: The Twitch ID
  • login String: The Twitch user Login (username that is found in the URL)
  • username String: The user's display name
  • followers Long: The user's follower count
  • views Long: The user's view count
  • profileImageURL String: The user's profile picture

Events​

TODO

Create an event​

Configuration​

TODO

Registration rules​

TODO

Rounds​

TODO

Scores​

TODO

Teams​

TODO

Register a team to an event​

TODO

Invite team members​

TODO

Logs​

TODO

Games​

TODO

Retrieve the game list​

TODO

Retrieve specific game data​

TODO