Let's talk about permissions

Let's talk about permissions

in API Development

Posted by: Lawton Campbell

Lawton Campbell

Web Programmer

Next

Currently the API keys have only a few permissions — account, characters, inventories and tradingpost. The intent behind permissions is to allow users to withhold portions of their account data when interacting with third-party applications. The individual endpoints are grouped functionally into coarse-grain permissions to prevent information overload.

We’ve got plans for quite a few more authenticated endpoints, and I wanted to get some opinions on some new scopes. The following are my rough notes for the API end-game (e.g., all permissions and authenticated endpoints we’ll ever have).

I’m mostly looking for any kind of suggestions/feedback regarding which new endpoints require which scopes, and anything I’ve forgotten or left out. There’s a couple of oddities (recipe unlocks) which could fit into a handful of categories (inventories makes sense for e.g., legendary tracker, but semantically unlocks/progression makes more sense). And I’m not really yet happy with some of the new permission names.

Anyway, the notes so far —

account
“Your account display name, ID, home world, and list of guilds. Required permission.”

  • required

characters
“Basic information about your characters.”

  • list characters
  • view basic character info

inventories
“Your account bank, material storage, and character inventories.”

  • account bank, material storage
  • character inventories
  • maybe recipe unlocks?

tradingpost
“Your Trading Post transactions.”

  • transaction history
  • current transactions
  • gold/items available for pickup

unlocks/wardrobe/fashion (name TBD)
“Your wardrobe unlocks and currently equipped skins.”

  • skin/dye/mail carrier/finisher/mini/etc unlocks
  • maybe currently equipped skins?
  • maybe recipe unlocks?

mail
“Received in-game mail.”

  • in-game mail

progression (name TBD)
“Your account-bound unlocks, timers, and progress.”

  • specialiation unlock progress
  • mastery progress
  • account achievements
  • world completion progression
  • daily dungeon/fractal reset progress
  • story progress, selected order, etc

pvp
“Your PvP stats, match history, reward track progression, and custom arena details.”

  • match history
  • custom arena state
  • reward track progression

guilds
“Guilds’ rosters, history, and MOTDs for all guilds you are a leader of.”

  • roster
  • ranks
  • event log
  • upgrades
  • motd

builds
“Your currently equipped specializations, traits, skills and equipment for all game modes.”

  • equipped specializations/traits
  • equipped skills
  • current equipment

wallet
“Your account’s wallet.”

  • …wallet

EDIT: scrap chat for now; that’s months away still.

contacts
“Read and write access to your contacts list.”

  • read access to friends/blocks, maybe also write access.

wvw
“Your WvW level and mastery point assignments.

  • puts wvw_level into the /v2/account response.
  • grants access to /v2/characters/:id/wvw_masteries (or something along those lines).

(edited by Lawton Campbell.8517)

Let's talk about permissions

in API Development

Posted by: Pilot.6094

Pilot.6094

One thing I strongly urge you consider before expanding permissions is a means for 3rd party apps to specify a required set of privileges. As it is, our site has to display lengthy instructions for end users about how to create a key with the appropriate permissions. It is a challenge from the start because our end users don’t even know what API stands for. If privileges expand (as they tend to do), it is going to greatly hinder our growth without a system in place to manage it.

We should be able to set the required permissions for our Apps to help users through the process. There are countless systems that do this today. I know an OAuth type model is out, due to ANet management preferences so how about a manifest model like Google Play, iTunes, Windows App Store, Overwolf etc. etc?

1) We register our Apps with ANet and upload an XML manifest specifying the required permissions.
2) The ANet account key page would have a dropdown that allows the end user to choose the App from a list for which they want to generate a key.
3) ANet processes the manifest and checks the requested permission boxes, making them all read only. (Better yet let the manifest specify Required or Optional permissions)
4) The user can choose to accept or decline. The key is generated the key if they accept, which they can copy it as usual.

This would be a very simple fix, for a major adoption hindrance. The added benefit of this is that ANet can build up a list set of registered 3rd party Apps and track adoption.

We need a way to specify required permissions to allow as many end users to complete the process as possible.

Let's talk about permissions

in API Development

Posted by: Anonanon.5412

Anonanon.5412

I was just thinking the other day that more MMOs need to have a phone app that lets you chat with friends and guild mates, on top of having basic “armory” functionality.

So to add to your guild chat read/write capabilities, please extend that to the entirety of our contact lists. This includes choosing which /g chat to join (basically changing which guild to rep straight from the phone), being able to chat with guild mates, whispering users, whispering friends, contact adding, contact renaming, contact blocking, block list management.

I think this is quite important to the game, it could prove to be very useful if something comes up in real life and you need to let your guild know ASAP that you’re going to be late for the guild mission reset

Let's talk about permissions

in API Development

Posted by: MatHack.4316

MatHack.4316

The list looks very solid and inclusive, here are the few comments I have:

unlocks/wardrobe/fashion (name TBD)

  • I would suggest skins as the name, all the things listed are basicly skins for a certain item (armor skins, mini skins, mail carrier skin). Dyes are so tightly related to armor skins that I believe most users would assume this to be included with this permission, and should not warrant changing the name to refect dyes are also included in this permission.
  • I think the current equipped skins should be listed under characters, the current visual representation of a character would be something that is basic to a character. It’s pretty much the first thing people see in-game when they look at a character.
  • Recipe unlocks are kinda weird in this endpoint, the rest is all about visual ‘effects’, I think inventories would be a more logical endpoint. The main purpose for recipe unlocks I see at the moment would be checking what the user can do/craft with his/her accumulated materials. You would need the inventories permission for that anyway, so I would put recipe unlocks under there as well.

progression (name TBD)

  • progression sounds like a good descriptive name, I think it’s a solid choice.
  • WvW ranks would be under here as well, I guess? Or does this merit a new permission wvw? Would it make more sense if we split it up in advance in case there would every be more wvw related stuff bound to your account/characters?
Far Shiverpeaks

Let's talk about permissions

in API Development

Posted by: zeeZ.5713

zeeZ.5713

We need a way to specify required permissions to allow as many end users to complete the process as possible.

That’s gonna be one hell of a dropdown menu :P Alternatively you could provide a way to generate some kind of string (like an encoded bitmask or json) that contains the permissions you’re asking for that the user can copy and paste to the key generation page to auto-select them.

Let's talk about permissions

in API Development

Posted by: Nicsword.3956

Nicsword.3956

progression (name TBD)

  • progression sounds like a good descriptive name, I think it’s a solid choice.
  • WvW ranks would be under here as well, I guess? Or does this merit a new permission wvw? Would it make more sense if we split it up in advance in case there would every be more wvw related stuff bound to your account/characters?

I like the idea of the WvW ranks. Have statistics that tell you how many of your guild mates mastered a particular trait.

Let's talk about permissions

in API Development

Posted by: Pilot.6094

Pilot.6094

Passing in a bit mask would be preferred but ANet seems to have ruled that out as they don’t want us direct linked to the GW2 account site. I’m open to anything that will help end users and adoption.

Let's talk about permissions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

Next

RE: Fixed permission sets.

Previously I’ve felt that, with only four permissions, it probably wasn’t needed. Looking at this list though, I’m starting to change my opinion and agree that we do need some way to make this a bit more straightforward.

Providing a standard request permissions like is strictly out (and I realize that most everyone already links to the API key page — which redirects through login), so I think the best we can do is either to provide a way to copy-paste permissions presets from a site, or to provide a way for sites to register presets somehow.

Anyway, I don’t want to get too far off-topic; so let’s table this for now.

So to add to your guild chat read/write capabilities, please extend that to the entirety of our contact lists. This includes choosing which /g chat to join (basically changing which guild to rep straight from the phone), being able to chat with guild mates, whispering users, whispering friends, contact adding, contact renaming, contact blocking, block list management.

That’s actually not a bad idea — now that I think about it, we can actually do read/write contact management stuff from the API. I kind of hesitate to put that under the “chat” permission (maybe “contacts” instead?).

I’m definitely not going to allow whispering arbitrary users via API though. Gold sellers in HotM are already annoying. The best I can do is the ability to whisper people who have added you as a friend, and even that’s not a certainty (needs internal discussion). Personally, I think that would provide a reasonable balance.

I think the current equipped skins should be listed under characters, the current visual representation of a character would be something that is basic to a character.

Hmm, that seems pretty reasonable. It fixes the ambiguity problem wherein both “inventories” and “fashion/unlocks/skins” provided access to the same data.

WvW ranks would be under here as well, I guess? Or does this merit a new permission wvw? Would it make more sense if we split it up in advance in case there would every be more wvw related stuff bound to your account/characters?

Hmm, the only bits I know of are your current WvW rank and chosen WvW masteries. I don’t know what our future plans are, but in the recent desert borderlands playtest I didn’t see anything new we’d expose via authenticated API, at least. If the current implementation stands (click a map icon to view upgrades) there’s a good case to be made for providing access current objective upgrades.

I’ve been looking for a place to put the WvW rank though, and since we’ve already got permissions for PvE (progression) and PvP (pvp), it would be symmetrical to have one for WvW too. I dunno.

Let's talk about permissions

in API Development

Posted by: MatHack.4316

MatHack.4316

Hmm, the only bits I know of are your current WvW rank and chosen WvW masteries. I don’t know what our future plans are, but in the recent desert borderlands playtest I didn’t see anything new we’d expose via authenticated API, at least. If the current implementation stands (click a map icon to view upgrades) there’s a good case to be made for providing access current objective upgrades.

I’ve been looking for a place to put the WvW rank though, and since we’ve already got permissions for PvE (progression) and PvP (pvp), it would be symmetrical to have one for WvW too. I dunno.

Just to clarify: I meant theoretical far future, not the coming stuff from HoT. I was speculating/theorizing there might be more account/character bound wvw stuff in the (far) future. This also ties in with what you are saying about splitting the playmodes into different permissions. Better to split it now, in case we might need it later.

Far Shiverpeaks

Let's talk about permissions

in API Development

Posted by: Devilsown.9376

Devilsown.9376

guilds
“Guilds’ rosters, history, and MOTDs for all guilds you are a member of.”

  • roster
  • ranks
  • event log
  • upgrades
  • motd

chat
“Read and write access to your guilds’ chat.”

  • read/write access to guild chat

That’s a little problematical, because it affects also other players. Every Guild Member has to trust every other Member that he/she don’t share his/her token with dubious webpages or archive every writen word to a DB, even he/she is offline.
This should need something like a allow/disallow from a guildleader and the status should be displayed under /v2/guild/id or (much better) somewhere ingame.

Let's talk about permissions

in API Development

Posted by: Archomeda.6472

Archomeda.6472

guilds
“Guilds’ rosters, history, and MOTDs for all guilds you are a member of.”

  • roster
  • ranks
  • event log
  • upgrades
  • motd

chat
“Read and write access to your guilds’ chat.”

  • read/write access to guild chat

That’s a little problematical, because it affects also other players. Every Guild Member has to trust every other Member that he/she don’t share his/her token with dubious webpages or archive every writen word to a DB, even he/she is offline.
This should need something like a allow/disallow from a guildleader and the status should be displayed under /v2/guild/id or (much better) somewhere ingame.

I agree. Although I’m pretty sure the devs are aware of this, it can’t hurt to reiterate it. Having access to the guild chat sounds really nice and it’s something that most people want (myself included). But it should be limited by new guild permissions. Maybe even separating the read and write access. If your account does not have sufficient permissions set by the guild leader, you’re out of luck.

On a similar note, even though this is not correct place to ask, but if this will be (eventually) added, I would like to be able to create more than 10 ranks. If the API permission gets added, I can imagine that leaders want to have more different ranks to allow/disallow certain people, even though the rank itself might be similar.
Also, “Admin Lower Ranks” should really be revisited (separate the ability to invite, promote/demote and kick for example). I really hope that the people who are responsible for the guild system are aware of this.

Let's talk about permissions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

Next

guilds
“Guilds’ rosters, history, and MOTDs for all guilds you are a member of.”

That’s a little problematical, because it affects also other players. Every Guild Member has to trust every other Member that he/she don’t share his/her token with dubious webpages or archive every writen word to a DB, even he/she is offline.
This should need something like a allow/disallow from a guildleader and the status should be displayed under /v2/guild/id or (much better) somewhere ingame.

That was a typo on my part. The description for the guilds permission actually reads “guilds you a a leader of”.

Until we get a checkbox in the guild permission system only guild leaders will be able to use the authenticated /v2/guild endpoints.

(EDIT: My previous response RE: chat permissions was not constructive enough; apologies)

For the chat endpoint, I’m somewhat opposed to restricting its access behind a guild permission because it seems to be a technical solution to a social issue. I’d originally imagined the chat to be self-policing: if someone was abusing it (where “abuse” is defined by the guild), the guild can just kick them. Having an explicit whitelist seems a bit silly to me — the current state is that guild chat is an implicit grant. It makes much more sense for the /v2/guild endpoints whose functionality is not diminished by having only one person be able to access them.

In any case, the chat stuff will take a significant effort to implement; as such we’ve got plenty of time to discuss the finer points of it. I think it would be best to start a new thread specifically for the implications of the chat endpoint.

(edited by Lawton Campbell.8517)

Let's talk about permissions

in API Development

Posted by: das Keks.5403

das Keks.5403

A nice thing for the inventories API would be a flag for each item’s binding.

So you could calculate how much gold you could get if you’d sell all your items. Of course that doesn’t work with account bound or soul bound items so you’d need some flag to see if its already bound the the account.

Let's talk about permissions

in API Development

Posted by: Archomeda.6472

Archomeda.6472

Until we get a checkbox in the guild permission system only guild leaders will be able to use the authenticated /v2/guild endpoints.

snip

In any case, the chat stuff will take a significant effort to implement; as such we’ve got plenty of time to discuss the finer points of it. I think it would be best to start a new thread specifically for the implications of the chat endpoint.

Fair enough. I have a different opinion about it, but that’s a discussion for another time. I got a bit carried away, sorry about that.

Looking over at

unlocks/wardrobe/fashion (name TBD)
“Your wardrobe unlocks and currently equipped skins.”

  • skin/dye/mail carrier/finisher/mini/etc unlocks
  • maybe currently equipped skins?
  • maybe recipe unlocks?

progression (name TBD)
“Your account-bound unlocks, timers, and progress.”

  • specialiation unlock progress
  • mastery progress
  • account achievements
  • world completion progression
  • daily dungeon/fractal reset progress
  • story progress, selected order, etc

unlocks/wardrobe/fashion

  • Seeing another post about moving currently equipped skins to character, I think that would be the best too. It is essentially a skinned item. By the way, don’t we already have access to a character’s equipment and to the current skin of an item? I think you mentioned the duplication as well.
  • I think it’s best to have this dedicated to unlocks only. This means the ones already listed (except equipped skins) + unlocked skins on your account (which is essentially the wardrobe). It would also remove the ambiguity about this permission I think.

progression

  • I would say that the name is fine. Progression means both your account and character progression.
  • I’m not really sure about this one, but the crafting disciplines are missing. Naturally I would say progression. But since unlocks holds the recipe unlocks, it can be under unlocks too. Especially since there’s also the crafting discovery in the game, which is again progression, but also a bit of an unlock.
    I think that recipe unlocks, crafting disciplines and crafting discoveries should be together in a permission, as they are tightly related to each other. Maybe get all three under progression and keep unlocks for account-wide unlocks only?

(edited by Archomeda.6472)

Let's talk about permissions

in API Development

Posted by: rodadams.5963

rodadams.5963

I think I’m okay with having a larger number of permissions which someone can use to fine tune what they want to give out…. but there would need to be some easy to use packages or presets which would be good for most people, covering the most common cases. Thus, site could tell people "get a key with the Trader’s preset (or perms X, Y, Z, W, K, & R)

Let's talk about permissions

in API Development

Posted by: MatHack.4316

MatHack.4316

Correct me if I’m wrong but stuff like recipe unlocks & crafting disciplines are char bound, not account bound, right? I’m not sure it would make sense to list these under (account) unlocks and progression. I also think these should at least have the name of the associated character included somewhere.

Far Shiverpeaks

Let's talk about permissions

in API Development

Posted by: Archomeda.6472

Archomeda.6472

Correct me if I’m wrong but stuff like recipe unlocks & crafting disciplines are char bound, not account bound, right? I’m not sure it would make sense to list these under (account) unlocks and progression. I also think these should at least have the name of the associated character included somewhere.

True. But as it currently stands, progression does not only have account-bound stuff. The specialization unlock, world completion, story and selected order are all character-bound.

But you have to keep in mind that having all of this categorized under one permission does not necessarily mean it will also be listed under one API endpoint. I think it’s perfectly reasonable to have it all under one progression permission.

(edited by Archomeda.6472)

Let's talk about permissions

in API Development

Posted by: Cire Lionheart.5318

Cire Lionheart.5318

Hello! I have been getting into working with this API and it has been a blast so far. Wish I would have built up my tools 2 years ago lol! Anyway, I was wondering if there were endpoints for PvE map completion. I would like to create a tool that lists out each zone with all its spots and create a checklist for each character and what they have unlocked.

I am also really looking forward to the guild endpoints so I can create tools to help me better manage my guild.

Rally to me Yaksalonians!

Let's talk about permissions

in API Development

Posted by: MatHack.4316

MatHack.4316

True. But as it currently stands, progression does not only have account-bound stuff. The specialization unlock, world completion, story and selected order are all character-bound.

But you have to keep in mind that having all of this categorized under one permission does not necessarily mean it will also be listed under one API endpoint. I think it’s perfectly reasonable to have it all under one progression permission.

Whoops, you’re totally right, I was thinking about endpoints instead of permissions… WAKE UP stupid brain!
But yeah, it should be perfectly fine to put account and character progression under 1 permission, as long as it will be multiple endpoints.

Far Shiverpeaks

Let's talk about permissions

in API Development

Posted by: Leablo.2651

Leablo.2651

If it’s not too late to add some input: The way the permission system currently works feels more like we are managing read permissions on database tables, which might make sense to us as developers but not for the privacy and security of users. I don’t think that segmentation of data based on in-game topics of interest makes a useful analogy for real-world escalations of trust.

The biggest issue with regard to privacy is personally identifying information. As far as the API is concerned, the big items here are the account and character names, which can be used to harass or track the player in-game or here on the forums, and all of which are exposed with very basic permissions. The account name isn’t really useful for the API itself but is exposed in virtually every key. Equally puzzling is that (mutable) character names are returned as the unique ID rather than a permanent and anonymous handle.

As for security, the API is thus far read-only and does not itself present any attack vector so it seems almost irrelevant whether they can view minutiae about the user’s data once they’ve already been given a key with basic permissions and with it, the biggest hints for employing some other attack vector, e.g. social engineering, if that’s what they were after.

As it currently stands I think you only need 2 permission sets: one for identifying information (i.e. account and character names, assuming the UID issue is addressed) and one for non-identifying information (everything else). I don’t really see any other significant gaps in trust or risk between a user and a third party they want to give a key to, though the bigger issue remains that there currently isn’t a meaningful separation in this regard.

If the app further exposes individual information to the public, and the user has some specific qualms about that, it should also be the app’s responsibility to provide finer privacy controls to the user, and that provision is something the user should take into consideration when deciding how much they want to trust the app.

Let's talk about permissions

in API Development

Posted by: DarkMagister.7429

DarkMagister.7429

1) We register our Apps with ANet and upload an XML manifest specifying the required permissions.

We need a way to specify required permissions to allow as many end users to complete the process as possible.

That’s a nice goal with an awful implementation idea. I think that is done in a far more simple way:
1. User comes to your site. User is urged to create an API ;-key with the given link
2. The link lists needed permission (as headers, post, etc., doe not matter)
3. The link leads to the My Account page here, to the page with already set permissions, following the given list.
4. The user creates the API with the proposed permissions and goes back to your site.

And it does not involve anet ding something but initial coding, which is vital if you want to see it in this life.

I was just thinking the other day that more MMOs need to have a phone app that lets you chat with friends and guild mates

That exists and is called Team Speak.

Let's talk about permissions

in API Development

Posted by: Pilot.6094

Pilot.6094

I agree DarkMaster however if you read the previous posts in the Dev forums ANet management made a decision that special links into their site will not be supported. For this reason a manifest is the only way to request any given set of permissions while addressing their concern. Very easy to implement, they just don’t seem to care.

Let's talk about permissions

in API Development

Posted by: DarkMagister.7429

DarkMagister.7429

hm, strange decision on their side, especially if all the “speciliality” is ?a=1,b=0,c=1,d=0
Yet it gives us some insight into what they don’t want to do to help developers outside of pure API providing, and the answer to that questions is “anything”. So I’d forget about any “uploading a manifest” and “register our Apps with ANet” ((

Let's talk about permissions

in API Development

Posted by: Lawton Campbell

Previous

Lawton Campbell

Web Programmer

As far as the API is concerned, the big items here are the account and character names, which can be used to harass or track the player in-game or here on the forums, and all of which are exposed with very basic permissions. The account name isn’t really useful for the API itself but is exposed in virtually every key. Equally puzzling is that (mutable) character names are returned as the unique ID rather than a permanent and anonymous handle.

So, for the account names — you can already see the account name of everyone you see in-game. You just have to add ‘em to your block list and the block list will show you their account name in the mouseover. It’s how you whisper enemies in WvW and other shenanigans — I’m not sure why it’s like that, but given how easily you can reveal account names I didn’t see much reason to obscure them in the API.

The character IDs are intentionally not provided for security reasons, and there’s nothing else in the character data that’s both immutable and uniquely identifies a character. It’s possible in the future (read: pretty far out) that we’ll fix this by providing an HMAC of the character ID or something, but it’s not really on the backlog. You can uniquely identify the characters within an account via the creation date (which I agree is backwards, but we’ve got worse warts).

Anyway, RE: the permissions discussion; I agree that the end-user UX is sub-optimal but I don’t forsee it changing, sorry

Let's talk about permissions

in API Development

Posted by: bxt.7691

bxt.7691

Hi,

Apologise for the resurrection but this seems like the most recent relevant post.

So I’ve been playing with the API and some of the more useful things for me, such as the members list, seem to be hidden behind a ‘guild leader only’ thing. How is that defined? Is that simply just the highest rank?

My guild rank is ‘Guild Leader’ and has all the permissions but it is the second highest rank. The guild’s founder, who comes online perhaps every 6 months or so to check all is well, retains the highest rank. This isn’t a problem and seems to works really well for a large guild and I generally see it much like the Queen in the UK… for the most part is ceremonial but does have the power to resolve things if one day is needed. Useful for context but I digress.

Anyway, is there some way to make it so it is dependant on a permission, maybe ideally a new one or if that isn’t possible something such as Edit Ranks or similar as for now I’m blocked from using useful APIs.

Edit: Nevermind, just seen all the discussions at https://github.com/arenanet/api-cdi/pull/7 so please ignore this. Have left it up in case anyone else has the same question.

(edited by bxt.7691)