api/token

↓ Methods.

module:api/token

Description:

  • API token based authentication, it reuses the users module to keep API token inside the same users table, as a special type of user, the login and secret columns use properties from the generated session by module:api/token.create.

    Parsed token session is stored in the context.session as an object:

    { type: "token", login: string, secret: string }`

    API tokens can be created via shell command:

    # bksh -user-add-token name test flags api -prefix api_
'api_7e717a99e4b642ce88010629d32921b7caf92f4d165c46f59f983f880aa25c78'
Source:

Methods

(static) parse(context) → {undefined|object}

Description:

  • Parse API token and return as session object with id and secret if valid or undefined

Source:
Parameters:
Name Type Description
context RequestContext
Returns:
Type Description
undefined | object

parsed token session if present, the format of the object is:

  • type: token
  • login - user login, public part of the token, UUIDv4, no prefix
  • secret - second part of the token as UUIDv4, hidden property
  • prefix - token prefix if existed

(static) prepare(context, optionsopt) → {object}

Description:

  • Create an API token to be saved in the database, stores it in context.session. The format is similar to module:api/session.

    Generated login and secret are random UUIDv4, so the secret hash without a salt is more about database exposure of secrets and not weak encryption.

    Still if the context options contains noHashSecret: true then session secret will not be hashed when comparing with user secret, for cases when storing raw secret is acceptable. Use module:api.contextOptions

    The session object contains the following properties:

    • type: token
    • login - generated UUIVv4 user login, no prefix
    • secret: generated UUIDv4 hashed with SHA256(optionally), to be saved in the users table as secret
    • token: concatenated prefix, login and unhashed secret, to be used in API Authorization header
    • raw: unhashed secret
Source:
Parameters:
Name Type Attributes Description
context RequestContext
options object <optional>
Properties
Name Type Attributes Description
prefix string <optional>

prefix for the token
noHashSecret boolean <optional>

do not hash the secret
Returns:
Type Description
object

a session object
Example
const session = api.token.create(context, { prefix: "test_" })
{ type: "token", login: 'a2a3912ba6df4d1ebc87278be49f8aa0', token: 'test_a2a....' }
const user = {
    login: session.login,
    secret: session.secret,
    name: "Test user",
    ....
};
await db.aput("bk_user", user);

(static) verify(context, secret, optionsopt)

Description:

  • Verify API token from Authorization header and sets user in the context on success, this can be used standalone or as middleware.

    It must be in format: Authorization: Basic base64(token) or Authorization: Bearer token,

    An API tokens are created by module:api/token.create and parsed by module:api/token.parse.

    If the context options contains noHashSecret: true then session secret will not be hashed when comparing with user secret, for cases when storing raw secret is acceptable. Use module:api.contextOptions

Source:
Parameters:
Name Type Attributes Description
context RequestContext
secret string
options object <optional>
Properties
Name Type Attributes Description
noHashSecret boolean <optional>

do not hash the secret