This is the API documentation for the arcdps-clears friend server.
The API always returns the entire state, which should replace the old state in the consumer. The exception to this is during errors, see individual endpoints for instructions on how to handle those.
This allows multiple instances consuming the API running in parallel to synchronize their status, which is useful when multiboxing.
This API makes heavy use of GW2 API subtokens. Make sure you are familiar with this feature.
As the addon allows using multiple keys, the authentication method also uses multiple keys.
This is done by providing x-auth-keys
as a header with a comma-separated list of key hashes.
Alternatively, you may provide multiple x-auth-keys
headers, each containing one key hash.
Do not combine these two approaches, commas are ignored if specifying multiple headers.
The key hashes are effectively passwords, and should be generated by SHA256(api_key)
. Knowledge of this hash allows
you to manipulate any data associated with it (such as related subtokens).
While it is not enforced by the API, you should only associate subtokens of api key A with the hash of A to avoid confusing users. Using the hash of A as the password also has the benefit of no extra storage being necessary.
Note that the hashes also identify keys in responses.
The API is used to get subtokens that may be used to request clears of your friends from the API. These subtokens are heavily restricted. They have a short expiration time (a day or so) to make it possible to revoke access for users without deleting an API key. You may have to request the key again when it's about to expire – the server guarantees having a new subtoken ready 1 hour before expiration.
They keys only allow the following endpoints:
- /v2/account/masteries – used to access the
last_modified
information with minimal information leaks about the account. - /v2/account/raids – used to access raid clear data
Note that in future, more endpoints may be added to support new features (such as dungeon clears and similar).
Users may set a key to be have one of two privacy settings:
- private – subtokens may only be accessed by friends (sharing to their account is required)
- public – anyone may request the subtoken
A list of public friends will be returned as part of the state.
This done by providing x-public-friends
as a header with a comma-separated list of account names (without leading :
)
Alternatively, you may provide multiple x-public-friends
headers, each containing one account name.
The state is returned as an answer to all successful requests, as JSON.
The following example assume that two keys were used in x-auth-keys
:
01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b,4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865
.
The keys
section contains the state of keys included in x-auth-keys
. The friends
section includes subtokens for
clears shared with any of the keys included in x-auth-keys
.
Note that no friends may be retrieved before adding a subtoken, as it is needed to verify the account name.
{
"keys": [
{
"key_hash": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b",
"shared_to": [],
"subtoken_added_at": null,
"subtoken_expires_at": null,
"account": null,
"public": false,
"disabled": false
},
{
"key_hash": "4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865",
"shared_to": [],
"subtoken_added_at": null,
"subtoken_expires_at": null,
"account": null,
"public": false,
"disabled": false
}
],
"friends": []
}
Both accounts have a subtoken added, first account is also shared to two friends. One of these friends does not have a subtoken available.
{
"keys": [
{
"key_hash": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b",
"shared_to": [
{
"account": "Account.1234",
"added_at": "2020-04-28T16:29:04.644008111Z",
"account_available": true
},
{
"account": "Account.5678",
"added_at": "2020-04-29T16:29:04.644008111Z",
"account_available": false
}
],
"subtoken_added_at": "2020-03-28T16:29:04.644008111Z",
"subtoken_expires_at": "2021-03-28T16:29:04.644008111Z",
"account": "OurAccount.1234",
"public": false,
"disabled": false
},
{
"key_hash": "4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865",
"shared_to": [],
"subtoken_added_at": "2020-03-28T16:30:04.644008111Z",
"subtoken_expires_at": "2021-03-28T16:30:04.644008111Z",
"account": "OurAccount.5678",
"public": false,
"disabled": false
}
],
"friends": []
}
This is an example that includes some subtokens for friends that were shared with one of our x-auth-keys
.
It also includes a request for one public friend that is available and one that is
not: x-public-friends: Friend.9876,FriendWithTypo.1234
.
{
"keys": [
{
"key_hash": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b",
"shared_to": [],
"subtoken_added_at": "2020-03-28T16:29:04.644008111Z",
"subtoken_expires_at": "2021-03-28T16:29:04.644008111Z",
"account": "OurAccount.1234",
"public": false,
"disabled": false
},
{
"key_hash": "4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865",
"shared_to": [],
"subtoken_added_at": "2020-03-28T16:30:04.644008111Z",
"subtoken_expires_at": "2021-03-28T16:30:04.644008111Z",
"account": "OurAccount.5678",
"public": false,
"disabled": false
}
],
"friends": [
{
"account": "Friend.1234",
"subtoken": {
"subtoken": "long.jwt.token.here",
"expires_at": "2021-04-28T17:25:00.181828132Z"
},
"public": false,
"known": true,
"shared_with": [
"01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
]
},
{
"account": "Friend.5678",
"subtoken": {
"subtoken": "another.long.jwt.token.here",
"expires_at": "2021-04-28T17:45:00.000000000Z"
},
"public": false,
"known": true,
"shared_with": [
"01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b",
"4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865"
]
},
{
"account": "Friend.9876",
"subtoken": {
"subtoken": "yet.another.long.jwt.token.here",
"expires_at": "2021-04-28T17:55:00.000000000Z"
},
"known": true,
"public": true,
"shared_with": []
},
{
"account": "FriendWithTypo.1234",
"subtoken": null,
"public": true,
"known": false,
"shared_with": []
}
]
}
The API supports the following endpoints:
- GET /state
- POST /key/add
- POST /key/share
- POST /key/unshare
- POST /key/public
The state endpoint returns the data described in the State section above.
In case subtoken_added_at
in keys
is null, use /key/add_subtoken
to add a subtoken or that key will not have any
data retrieved.
This endpoint adds a subtoken for a key. This subtoken may be updated later, we recommend doing that when the expiration is less than 6 months away.
key_hash
– key hashsubtoken
– GW2 API subtoken; see requirements below
The subtoken expiration date has to be at least 300 days away, we recommend making it as long as possible (the GW2 API caps the expiration at 1 year).
account
progression
The subtoken urls have to be restricted, and have to include the following urls:
- /v2/tokeninfo – used to verify token validity
- /v2/account – used to access account name, this is never shared further to avoid impersonation
- /v2/account/achievements – may be used in the future to add features that require checking achievements
- /v2/account/dungeons – may be used in the future for dungeon clears
- /v2/account/masteries – used to access the
last_modified
information with minimal information leaks about the account. - /v2/account/raids – used to access raid clear status
- /v2/account/worldbosses – may be used in the future for world boss clears (unlikely)
- /v2/createsubtoken – used to further restrict information when sharing to friends
The token is rejected with status code 400 if these requirements are not fulfilled.
Allows a friend to access the clears of a key.
key_hash
– key hashaccount
– account name of the friend; anyone who has an api key with this account name gains access
Revokes the access to the clears of a key for a friend. Note that it may take up to a day to lose access because of subtoken expiration times.
key_hash
– key hashaccount
– account name of the friend; having an api key with this account name is no longer sufficient to gain access
Configures accessibility of subtokens.
key_hash
– key hashpublic
– false if only friends may access, true if anyone may access subtokensdisabled
- if true, nobody may access (regardless of friend settings)