Hello all,

I put together a quick change to the API to allow some more fine-tuned control over sharing API keys a few weeks ago, and I had a chance to deploy it today. I have added an endpoint for creating what I'm calling "subtokens".

Recent API Updates

First, here is the change in list format:

Added the /v2/createsubtoken endpoint

Subtokens

As a warning: this change's uses are niche.

A subtoken is a special API key that can be used anywhere a normal API key can be used. It is simply a wrapper around a regular API key with reduced permissions. It can be created by accessing /v2/createsubtoken with several options:

Subset of permissions (e.g. account, inventories)

Expire time

List of urls that can be accessed (optional: if no urls are provided, then all urls are allowed)

Here is an example that shows the full functionality:

GET https://api.guildwars2.com/v2/createsubtoken?permissions=account &expire=2019-12-25%2012:34:56 &urls=/v2/characters/My%20Cool%20Character,/v2/account/home/cats Authorization: Bearer MY_API_KEY

The API will respond with:

{ "subtoken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ3YlRodVdNNGExMUduZlpYSTdaa0pHck52 SVVPUWhMejZHTXpOeE9TUC1rIiwiaWF0IjoxNTU4Mzk3OTUwLCJleHAiOjE1NzczMDYwOTYsInBlcm1pc3Npb25zIjpbIn Byb2dyZXNzaW9uIiwiYWNjb3VudCIsInVubG9ja3MiXSwidXJscyI6WyIvdjIvY2hhcmFjdGVycy9NeSUyMENvb2wlMjBD aGFyYWN0ZXIiLCIvdjIvYWNjb3VudC9ob21lL2NhdHMiXX0.UdLlafgo8lxkb1Hn88paZT83aw_9mHEYVZJLDgObNSc" }

I can then see what cats I have unlocked with this large subtoken

GET https://api.guildwars2.com/v2/account/home/cats Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ3YlRodVdNNGExMUduZlpYSTdaa 0pHck52SVVPUWhMejZHTXpOeE9TUC1rIiwiaWF0IjoxNTU4Mzk3OTUwLCJleHAiOjE1NzczMDYwOTYsInBlcm1pc3Npb25zI jpbInByb2dyZXNzaW9uIiwiYWNjb3VudCIsInVubG9ja3MiXSwidXJscyI6WyIvdjIvY2hhcmFjdGVycy9NeSUyMENvb2wlM jBDaGFyYWN0ZXIiLCIvdjIvYWNjb3VudC9ob21lL2NhdHMiXX0.UdLlafgo8lxkb1Hn88paZT83aw_9mHEYVZJLDgObNSc

and get normal results.

The request will be rejected if:

The reduced permissions do not meet the permission requirements of the endpoint

The subtoken time is expired

The request url does not match the restricted url set (unless there are no url restrictions)

The original API key which was used to create the subtoken is deleted

Subtoken uses

As I admitted earlier, there aren't a huge amount of uses for a subtoken. Here are the two use-cases I considered while making this change:

First and foremost, subtokens lets an app (App 1) accept & store an API key from a player and then pass that API key on to another app (App 2) with more control over what App 2 can do with the player's key.

The other case is for savvy users who want more control over what they share with their API key. They can use the endpoint to generate subtokens to hand over to apps with, e.g. expire times or restrictions to certain character endpoints.

I'd love to hear thoughts and feedback for this change, as well as any bug reports.

Thanks!

Snider

EDIT: Added a bit about deleting the original API Key