Proposal for API Authentication #1414

With the creation of an API upcoming on the roadmap, I thought It'd be good to start planning out the authentication method for the API. I welcome advice or concerns on this, since the authentication is something I want to get right. These are my initial thoughts:

Proposal

• A new system 'API Access' role permission is made available for admins to assign to roles.
• Users within a role that has 'API Access' will be able to generate API tokens in their profile.
  • Tokens will be generated as a random 32 char string, bcrypted and saved to DB, The raw token will be passed back as plaintext to the user on generation, a single time only.
  • On token creation, Users will be able to provide a name to indicate usage.
  • On token creation, you will be able to set an expiry date, after which the token becomes invalid.
  • A user will be able generate multiple tokens if they wish.
  • Tokens will show their generation date.
  • Tokens can be deleted at any time.
• Tokens will be used via a Authorization: Token <token_val> header.
• API access will inherit the permissions of the user the token has been generated against. If a tighter permission scope is needed a new 'API-specific' user could be created with more selective permissions.
• Users with a 'Manage Users' permission but lacking 'API Access' permission will be able to edit/delete existing tokens but not generate new tokens.
• Users with both 'Manage Users' and 'API Access' permission will be able to generate tokens for others in addition to edit and delete existing tokens.
• On each API request, the token expiry will be checked. If expired an error response will be returned right away with a message or header that indicates token expiry.

Implementation Considerations

These are non-proposal items we'll need to cover with tests on implementation

• The user's 'API Access' permission should be checked on each request instead of inferring they should have the permission by having a token, since roles could dynamically change.

Questionables

• Should someone with just a 'Manage Users' permission be able to manage someone else's tokens or should they also require 'API Access'? I'm thinking the latter.
• Would it be worth displaying a "Last Used" date against the token? Would require an extra DB write per request, but might be worth it to identify active API usage.