# balena-auth > Balena session authentication utilities Latest version **6.1.1** (published 2026-06-10) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install balena-auth pnpm add balena-auth yarn add balena-auth bun add balena-auth ``` ## Health **Score 60/100 (C)** — status: active. Positive: has types; no vulnerabilities; has provenance; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 6.1.1 | | Published | 2026-06-10 | | First published | 2018-10-17 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=18.0.0 | | Dependencies | 4 | | Unpacked size | 43.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 4 | | Author | Balena Team | | Maintainers | balena.io | | Keywords | balena, auth, jwt, api-key, session | ## Links - npm: https://www.npmjs.com/package/balena-auth - Repository: https://github.com/balena-io-modules/balena-auth - Issues: https://github.com/balena-io-modules/balena-auth/issues - npm.io page: https://npm.io/package/balena-auth ## Dependencies (4) - [tslib](https://npm.io/package/tslib.md) ^2.0.0 - [jwt-decode](https://npm.io/package/jwt-decode.md) ^3.1.2 - [balena-errors](https://npm.io/package/balena-errors.md) ^5.0.0 - [balena-settings-storage](https://npm.io/package/balena-settings-storage.md) ^9.0.0 ## Alternatives - [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads - [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads - [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads - [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads - [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads ## Recent versions - 6.1.1 (latest) — 2026-06-10 - 6.1.1-build-balena-errors-4fcd80d74fe32566ef9749d04ca811595d318355-1 (build-balena-errors) — 2026-06-10 - 6.1.0-build-export-error-types-5a41fa48281c4f623902d5ddcbb9b7db06af80e6-1 (build-export-error-types) — 2026-03-24 - 6.0.1-build-jwt-decode-3-8179bdfc955741da8e3064d18ce415c6c4220f00-1 (build-jwt-decode-3) — 2024-02-23 - 6.0.0-build-jwt-decode-3-e0494bd84f2fcaea1fa04a118aa63ba965db29a8-1 (build-jwt-decode-3-e0494bd84f2fcaea1fa04a118aa63ba965db29a8) — 2024-02-23 - 6.0.0-build-node-18-cfeecc8af7afda08e673cc6bde658cfa20879c82-1 (build-node-18-cfeecc8af7afda08e673cc6bde658cfa20879c82) — 2024-02-23 - 5.1.0-build-data-directory-false-2cc4958bb2916775fecbc258f43b23c46333b661-1 (build-data-directory-false-2cc4958bb2916775fecbc258f43b23c46333b661) — 2023-07-28 - 5.0.1-build-isolation-tests-0404c937564fe24e0b6ba1cca49db776bcfeaa75-1 (build-isolation-tests) — 2023-07-28 - 5.0.1-build-isolation-tests-4ab0f9fc4e6b4a4bebd0639ae66edbdb4d622c45-1 (build-isolation-tests-4ab0f9fc4e6b4a4bebd0639ae66edbdb4d622c45) — 2023-07-28 - 5.0.0-build-bump-node-balena-settings-storage-1a5128a7e9d871793b664d715e4857cb7743b911-1 (build-bump-node-balena-settings-storage-1a5128a7e9d871793b664d715e4857cb7743b911) — 2023-07-24 - 4.2.1-build-klutchell-patch-1-d326127df55010e4f4f208cdadbad2ffbb9b32f9-1 (build-klutchell-patch-1) — 2023-07-13 - 4.2.0-build-get2FAStatus-266c8bc9b12d13fd96ce0ae6b12d7767a27030d8-1 (build-get2FAStatus) — 2023-05-25 - 4.2.0-build-get2FAStatus-197ab120349279ddda0b77a9e9b104fc40e1c0a7-1 (build-get2FAStatus-197ab120349279ddda0b77a9e9b104fc40e1c0a7) — 2023-05-25 - 4.1.3-build-fix-async-tests-027af56893911b7b6a95c6743eb90cae86cc3f86-1 (build-fix-async-tests) — 2023-05-25 - 4.2.0-build-has2fa-dd86556a2ea2fc88f598e74d9a49f1a0ae0fe0d2-1 (build-has2fa-dd86556a2ea2fc88f598e74d9a49f1a0ae0fe0d2) — 2023-05-24 - … 31 more at https://npm.io/package/balena-auth/versions ## README balena-auth ----------- [![npm version](https://badge.fury.io/js/balena-auth.svg)](http://badge.fury.io/js/balena-auth) [![dependencies](https://david-dm.org/balena-io-modules/balena-auth.png)](https://david-dm.org/balena-io-modules/balena-auth.png) [![Build Status](https://travis-ci.org/balena-io-modules/balena-auth.svg?branch=master)](https://travis-ci.org/balena-io-modules/balena-auth) Join our online chat at [![Gitter chat](https://badges.gitter.im/balena-io/chat.png)](https://gitter.im/balena-io/chat) Balena session authentication utilities Role ---- The intention of this module is to provide low level access to how a balena authentication tokens are parsed and persisted. **THIS MODULE IS LOW LEVEL AND IS NOT MEANT TO BE USED BY END USERS DIRECTLY**. Unless you know what you're doing, use the [balena SDK](https://github.com/balena-io/balena-sdk) instead. Installation ------------ Install `balena-auth` by running: ```sh $ npm install --save balena-auth ``` Documentation ------------- The module returns a class that you use to get an instance of the auth module. It accepts the following params: | Param | Type | Description | | --- | --- | --- | | options | Object | options | | [options.dataDirectory] | string \| false | the directory to use for storage in Node.js or false to create an isolated in memory instance. Values other than false are ignored in the browser. | | [options.tokenKey] | string | the key used to store the last token in the storage. `token` by default. | **Example** ```js import BalenaAuth from 'balena-auth'; const auth = new BalenaAuth({ dataDirectory: '/opt/cache/balena', tokenKey: 'token' }); ``` * [auth](#module_auth) * [~setKey(key)](#module_auth..setKey) ⇒ Promise.<void> * [~hasKey()](#module_auth..hasKey) ⇒ Promise.<Boolean> * [~removeKey()](#module_auth..removeKey) ⇒ Promise * [~getType()](#module_auth..getType) ⇒ Promise.<TokenType> * [~getKey()](#module_auth..getKey) ⇒ Promise.<string> * [~getAge()](#module_auth..getAge) ⇒ Promise.<(number\|undefined)> * [~isExpired()](#module_auth..isExpired) ⇒ Promise.<boolean> * [~isValid()](#module_auth..isValid) ⇒ Promise.<boolean> * [~get2FAStatus()](#module_auth..get2FAStatus) ⇒ Promise.<('not\_required'\|'pending'\|'passed')> * [~needs2FA()](#module_auth..needs2FA) ⇒ Promise.<boolean> ### auth~setKey(key) ⇒ Promise.<void> **Kind**: inner method of [auth](#module_auth) **Summary**: Set the key **Access**: public | Param | Type | | --- | --- | | key | String | **Example** ```js auth.setKey('...').then(() => { ... }); ``` ### auth~hasKey() ⇒ Promise.<Boolean> **Kind**: inner method of [auth](#module_auth) **Summary**: Has a key **Returns**: Promise.<Boolean> - has key **Access**: public **Example** ```js auth.hasKey().then((hasKey) => { ... }); ``` ### auth~removeKey() ⇒ Promise This promise is not rejected if there was no key at the time of removal. **Kind**: inner method of [auth](#module_auth) **Summary**: Remove the key **Access**: public **Example** ```js auth.removeKey(); ``` ### auth~getType() ⇒ Promise.<TokenType> **Kind**: inner method of [auth](#module_auth) **Summary**: Gets the key type **Access**: public **Example** ```js auth.getType().then((type) => { ... }); ``` ### auth~getKey() ⇒ Promise.<string> **Kind**: inner method of [auth](#module_auth) **Summary**: Gets the key **Access**: public **Example** ```js auth.getKey().then((key) => { ... }); ``` ### auth~getAge() ⇒ Promise.<(number\|undefined)> **Kind**: inner method of [auth](#module_auth) **Summary**: Gets the token age **Access**: public **Example** ```js auth.getAge().then((age) => { ... }); ``` ### auth~isExpired() ⇒ Promise.<boolean> **Kind**: inner method of [auth](#module_auth) **Summary**: Checks if token is expired **Access**: public **Example** ```js auth.isExpired().then((expired) => { ... }); ``` ### auth~isValid() ⇒ Promise.<boolean> **Kind**: inner method of [auth](#module_auth) **Summary**: Checks if token format is valid **Access**: public **Example** ```js auth.isValid().then((valid) => { ... }); ``` ### auth~get2FAStatus() ⇒ Promise.<('not\_required'\|'pending'\|'passed')> **Kind**: inner method of [auth](#module_auth) **Summary**: Gets whether passing a 2FA challenge is pending, passed or not required. **Access**: public **Example** ```js auth.get2FAStatus().then((get2FAStatus) => { ... }); ``` ### auth~needs2FA() ⇒ Promise.<boolean> **Kind**: inner method of [auth](#module_auth) **Summary**: Checks whether passing 2FA is pending/needed **Access**: public **Example** ```js auth.needs2FA().then((needs2FA) => { ... }); ``` Support ------- If you're having any problem, please [raise an issue](https://github.com/balena-io-modules/balena-auth/issues/new) on GitHub and the balena team will be happy to help. Tests ----- Run the test suite by doing: ```sh $ npm test ``` Contribute ---------- - Issue Tracker: [github.com/balena-io-modules/balena-auth/issues](https://github.com/balena-io-modules/balena-auth/issues) - Source Code: [github.com/balena-io-modules/balena-auth](https://github.com/balena-io-modules/balena-auth) Before submitting a PR, please make sure that you include tests, and that [tslint](https://palantir.github.io/tslint/) runs without any warning: ```sh $ npm run lint ``` License ------- The project is licensed under the Apache 2.0 license. --- _Source: https://npm.io/package/balena-auth · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._