This API version is in development and is not stable. Do not use it in release versions of your software.
Authenticate client with one of the allowed authentication backends:
POST /v1a/client/auth
Parameter | Type | Description |
---|---|---|
projectId |
string | Project identifier |
auth |
object | Credentials |
auth.itchJwtToken |
string | itch.io JWT token |
auth.steamEncryptedTicket |
string | Steam encrypted ticket |
auth.testKey |
string | Project’s test key |
auth.testId |
string integer | Index of test user |
The auth
parameter must contain credentials for exactly one authentication backend.
Field | Type | Description |
---|---|---|
status |
string | "authenticated" or "notAuthenticated" |
clientToken |
string | Opaque client token. |
{
"projectId": "abcdefghijk",
"auth":
{
"itchJwtToken": "abcdefghijk0123456789",
}
}
{
"status": "authenticated",
"clientToken": "abcdefghijk0123456789"
}
{
"status": "notAuthenticated",
"error": "bad token"
}
Place authenticated client into match queue. Returns match token, which allows to request status of matching process.
POST /v1a/client/match
Header | Description |
---|---|
Authorization |
Format: "Bearer " + clientToken |
Parameter | Type | Description |
---|---|---|
clientToken |
string | clientToken from authentication step |
teamSizes |
array of integers | Number of players in each team in a future game session |
maxMatchTime |
integer | How long to wait for match |
matchTag |
string (optional) | Additional parameter for match queue |
serverTag |
string (optional) | Additional parameter for match queue |
info |
any (optional) | Arbitrary information about player, automatically shared with all players in a session |
Field | Type | Description |
---|---|---|
matchToken |
string | Match token allows to get status of matching process. |
Authorization: Bearer CLIENT_TOKEN
{
"teamSizes": [1, 1],
"maxMatchTime": 30,
"matchTag": "hardcore_mode",
"info":
{
"ip": "1.2.3.4",
"port": 1234
}
}
{
"matchToken": "MATCH_TOKEN"
}
Retrieve status of matching process.
GET /v1a/client/match/{matchToken}
(replace {matchToken}
with actual match token)
Header | Description |
---|---|
Authorization |
Format: "Bearer " + clientToken |
None.
Field | Type | Description |
---|---|---|
status |
string | notFound , inProgress , matched or failed |
session.externalSessionId |
string | Random session id |
session.sessionToken |
string | Session token allows to upload session results |
session.teams |
array of array of objects | Description of teams |
session.teams[i][j].info |
any (optional) | Arbitrary information about player, specified in info parameter when requesting match |
session.teams[i][j].ourTicket |
string | Ticket for presenting by us to this player in order to authenticate with them |
session.teams[i][j].theirTicket |
string | Ticket this player must present to us in order to authenticate themselves |
session.teamIndex |
integer | Index of a team we are in |
session.mateIndex |
integer | Our index within a team |
session.server |
object or null | Server information, if there’s a server |
session.server.info |
any (optional) | Arbitrary information specified by server |
session.server.ourTicket |
string | Ticket for presenting to server in order to authenticate |
reason |
string | Failure reason, in case status is failed |
{
"status": "inProgress"
}
This example corresponds to the match request example above.
Note that ourTicket
and theirTicket
are missing for our player, as we don’t need to authenticate with ourselves.
{
"status": "matched",
"session":
{
"externalSessionId": "EXTERNAL_SESSION_ID",
"sessionToken": "SESSION_TOKEN",
"teams":
[
[
{
"info":
{
"ip": "1.2.3.4",
"port": 1234
},
"ourTicket": null,
"theirTicket": null
}
],
[
{
"info":
{
"ip": "5.6.7.8",
"port": 5678
},
"ourTicket": "CLIENT_0_TICKET_FOR_CLIENT_1",
"theirTicket": "CLIENT_1_TICKET_FOR_CLIENT_0"
}
]
],
"teamIndex": 0,
"mateIndex": 0,
"server":
{
"info":
{
"ip": "9.10.11.12",
"port": 4321
},
"ourTicket": "CLIENT_0_TICKET_FOR_SERVER",
"theirTicket": "SERVER_TICKET_FOR_CLIENT_0"
}
}
}
Cancel matching process.
DELETE /v1a/client/match/{matchToken}
(replace {matchToken}
with actual match token)
Header | Description |
---|---|
Authorization |
Format: "Bearer " + clientToken |
None.
None.
Upload session results from client.
POST /v1a/client/session/{sessionToken}/result
(replace {sessionToken}
with actual session token)
Header | Description |
---|---|
Authorization |
Format: "Bearer " + clientToken |
Parameter | Type | Description |
---|---|---|
status |
string | finished or cancelled |
ranks |
array of integers | Ranks of teams |
None.
Request matches from server side.
POST /v1a/server/match
Parameter | Type | Description |
---|---|---|
projectId |
string | Project identifier |
projectServerToken |
string | Server token from project settings |
serverTag |
string (optional) | Additional parameter for choosing sessions |
name |
string | Unique server name |
info |
any (optional) | Arbitrary information about server, which will be shared with clients automatically |
timeout |
integer (optional) | After what time to expire request for matches, in seconds |
Field | Type | Description |
---|---|---|
status |
string | Must be registered |
{
"projectId": "abcdefghijk",
"projectServerToken": "PROJECT_SERVER_TOKEN",
"serverTag": "SERVER_TAG",
"name": "EU_WEST_1",
"info":
{
"ip": "9.10.11.12",
"port": 4321
},
"timeout": 30
}
{
"status": "registered"
}
Cancel requesting matches from server side.
DELETE /v1a/server/match
Parameter | Type | Description |
---|---|---|
projectId |
string | Project identifier |
projectServerToken |
string | Server token from project settings |
name |
string | Unique server name |
Field | Type | Description |
---|---|---|
status |
string | Must be cancelled |
{
"projectId": "abcdefghijk",
"projectServerToken": "PROJECT_SERVER_TOKEN",
"name": "EU_WEST_1"
}
{
"status": "cancelled"
}
Get sessions on server side.
POST /v1a/server/match/sessions
Parameter | Type | Description |
---|---|---|
projectId |
string | Project identifier |
projectServerToken |
string | Server token from project settings |
name |
string | Unique server name |
Field | Type | Description |
---|---|---|
sessions |
array of objects | Sessions objects |
sessions[i].externalSessionId |
string | Random session id |
sessions[i].serverSessionToken |
string | Server session token |
sessions[i].teams |
array of array of objects | Description of teams in a session, in the same format as in client match response |
sessions[i].matchTag |
string | Match tag |
sessions[i].serverTag |
string | Server tag |
{
"projectId": "abcdefghijk",
"projectServerToken": "PROJECT_SERVER_TOKEN",
"name": "EU_WEST_1"
}
{
"sessions":
[
{
"externalSessionId": "EXTERNAL_SESSION_ID",
"serverSessionToken": "SERVER_SESSION_TOKEN",
"teams":
[
[
{
"info":
{
"ip": "1.2.3.4",
"port": 1234
},
"ourTicket": "SERVER_TICKET_FOR_CLIENT_0",
"theirTicket": "CLIENT_0_TICKET_FOR_SERVER"
}
],
[
{
"info":
{
"ip": "5.6.7.8",
"port": 5678
},
"ourTicket": "SERVER_TICKET_FOR_CLIENT_1",
"theirTicket": "CLIENT_1_TICKET_FOR_SERVER"
}
]
],
"matchTag": "MATCH_TAG",
"serverTag": "SERVER_TAG"
}
]
}
Upload session results from server.
POST /v1a/server/session/{serverSessionToken}/result
(replace {serverSessionToken}
with actual server session token)
Parameter | Type | Description |
---|---|---|
status |
string | finished or cancelled |
ranks |
array of integers | Ranks of teams |
None.