Account Linkage
Account linkage flow
Account linkage is the mechanism that allows FACEIT and partners to couple users and communicate with each other.
We use the authorization code flow in OAuth2 protocol to link FACEIT and partner user accounts.
Example of linking account flow with the real partner.
White Market uses Steam authentication on its side. The other partners can implement any type of authentication, such as a password or via another platform.
Required changes from the partner
Create a client for FACEIT
A client concept is part of OAuth2 protocol. The partner must store on their side the following information:
Client ID. It’s generated by the Partner.
Client secret. It’s generated by the Partner.
Redirect URL. It’s provided by FACEIT.
Client ID and client secret are used to authorize requests when linking user accounts.
Authorization page
The partner must implement the authorization page. FACEIT platform will open this page when users press the “connect partner“ button. The authorization page can be opened in a new tab or popup depending on the browser, FACEIT doesn’t control it. The user should be able to log in with the partner account on this page. FACEIT platform adds the following query parameters in the authorization URL:
| Parameter name | Description |
|---|---|
| client_id | Client ID that partner created for FACEIT. |
| redirect_uri | The partner should use this URI to redirect users back after authentication. The partner MUST check that passed redirect_uri matches with the client URL that was stored for the client. |
| state | A random sequence of symbols. The partner only needs to add it in redirect_uri when redirecting. |
| scope | Optional parameter that restricts access to partner API. It defines the set of actions that FACEIT can perform on the partner side after successful authorization, for instance, getting user information. If the partner doesn’t restrict access, FACEIT won’t add scope to the authorization URL. |
| response_type | It’s a constant value code that determines the authorization processing flow to be used. |
Authorization URL example:
https://<partner domain>/oauth2/authorize?scope=person_profile&redirect_uri=https://api.faceit.com/account-integration/v1/platforms/<partner>/redirect&response_type=code&client_id=7077a2af28304560f409d02499190abf&state=31735de7-d93c-48bc-8a32-8a870e2b4824
The path (in this example oauth2/authorize) can be anything.
After successful authorization, the partner redirects users back to FACEIT, the following query parameters should be added to the redirect URL:
| Parameter name | Description |
|---|---|
| code | One-time code that is used to get access token. The code should be issued for client with the requested ID. |
| state | A random sequence of symbols from the authorization URL. |
Successful redirect URL example:
https://api.faceit.com/account-integration/v1/platforms/whitemarket/redirect?state=31735de7-d93c-48bc-8a32-8a870e2b4824&code=532487652984365923846
If a user fails authentication for some reason, the partner must add to the redirect URL the following query parameters:
| Parameter name | Description |
|---|---|
| error | Human readable error code. |
Failed redirect URL example:
https://api.faceit.com/account-integration/v1/platforms/<partner>/redirect?error=access_denied
The partner can send any error codes here.
Token endpoint
The partner must implement an endpoint to exchange an authorization code for an access token and refresh an access token.
- Endpoint
POST https://<partner domain>/oauth2/token
Header (required)
Content-type: application/x-www-form-urlencoded;charset=UTF-8Authorization: Basic base64(client_id:client_secret)Data
| Parameter name | Parameter type | Description |
|---|---|---|
| grant_type | string | It’s a constant value: authorization_code for code exchanging refresh_token for refreshing access token. |
| code | string | One-time code. The value from redirect URL. For authorization_code |
| redirect_uri | string | The redirect URL that is used in the authorization flow. |
| refresh_token | string | Refresh token. For refresh_token. |
An example of a well-formed request:
POST https://<partner domain>/oauth2/token
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
client_id=2345234345&code=234523452346&grant_type=authorization_code&redirect_uri=https://api.faceit.com/account-integration/v1/platforms/<partner>/redirect?state=a0ae591e-748b-49d3-90a8-ef63c08e5095
Method returns:
200 HTTP code in successful token exchange with JSON encoded body with the following parameters:
| Parameter name | Parameter type | Description |
|---|---|---|
| access_token | string | The access token that provides access to the partner API. |
| refresh_token | string | The refresh token is used to refresh expired an access token. |
An example of a well-formed successful response:
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}
4XX HTTP code in error case with JSON encoded body with the following parameters:
| Parameter name | Parameter type | Description |
|---|---|---|
| error | string | Human readable error code. |
An example of a well-formed failed response:
{
"error":"invalid_request"
}
User info endpoint
The partner must implement an endpoint to get user information.
- Endpoint
GET https://<partner domain>/oauth2/userinfo
Header (required)
Authorization: Bearer <access_token>
Method returns:
200 HTTP code with JSON encoded body with the following parameters:
| Parameter name | Parameter type | Description |
|---|---|---|
| sub | string | User ID from the partner system. |
| nickname | string | User nickname from the partner system. If the partner doesn’t have nicknames for users, then the partner returns the user IDs as nicknames. |
An example of a well-formed successful response:
{
"sub":"246254352345",
"nickname":"progamer1337"
}
4XX HTTP code in error case with JSON encoded body with the following parameters:
| Parameter name | Parameter type | Description |
|---|---|---|
| error | string | Human readable error code. |
An example of a well-formed failed response:
{
"error":"invalid_request"
}
Integration steps
FACEIT shares with partner redirect URL and IP’s if they are required for whitelisting.
The partner implements:
a. Authorization page
b. Token endpoint
c. User info endpoint
The partner shares with FACEIT:
a. Client id
b. Client secret
FACEIT and partner test account linkage on stage
FACEIT and partner test account linkage on prod
Limitation
Please be aware that each integration must be linked to a specific organizer responsible for prize distribution. If you have multiple CRMs due to geographical restrictions or other factors, they will need to be associated with separate organizers, leading to divided competitions. Therefore, we recommend consolidating all your user data into a single CRM to simplify management and avoid splitting the competitions.