diff --git a/Design:-API-Token-management.md b/Design:-API-Token-management.md new file mode 100644 index 0000000..e7370b2 --- /dev/null +++ b/Design:-API-Token-management.md @@ -0,0 +1,34 @@ +# Description +Access to the admin API is based on access tokens. +With password-based auth, a simple flow is available to get exchange username/password for a session token. + +With the introduction of strategy-based auth, it is much harder to automate access to the api. For example, where auth is based on interaction with the Twitter website. + + +## Configuration +The `apiAccessTokens` propety in `settings.js` can used to add the setting-defined accessToken. + +```Javascript +apiAccessTokens: [ + // you can add multiple access tokens + { + token: "0123456789abcdefghijk", // access token + user: "root", // user + scope: ["*"] // scope + } +] +``` + +* **acccess token** +The access token is used to access the adminAPI by setting it in HTTP Bearer header. The value should be a string with the different length from session token in order to avoid a conflict between access tokens and session tokens. + +* **user** +The user is used to identify as which user access the adminAPI. The value in the user should be the `username` property in any record in `adminAuth.users` property in `settings.js` file. + +* **scope** +The scope is used to specify which access permissions is granted to the specified user. This value should be a array object like `permissions` property in a record in `adminAuth.users` property in `settings.js` file. + +## Behaver/Implementation +* The verify process for access token is implemented in the exisiting session token functions in `red/api/auth/tokens.js`. This means that we should NOT change the other functions. +* If same access tokens are defined in `apiAccessTokens` property in `settings.js` file, the only last access token is active. This means that scope properties are NOT merged. +* If the specified access token is same to a session token, the specified access token is active but the session token is NOT active.