Improve this doc

Account management

Sign up

In order to use balena and deploy code to devices you will need a balena account.

If you don't already have a account head over to our signup page. When you create your account, you will be asked to enter you email address and create a password for the account. You password needs to be at least 8 characters long.

Access tokens

Access tokens are used for authentication in the balena API, CLI, and Node.js and Python SDKs. They are managed in the Access tokens tab of the Preferences page, which can be found via the dropdown menu in the upper-right corner of the dashboard:

There are two types of access tokens: session tokens and API keys. Both authentication types provide user-level permissions, meaning any user or application with one of these tokens can make changes across devices, applications, and the user account.

Session tokens

Session tokens are retrieved from the Preferences page, and they can be refreshed with the API. These tokens expire after seven days, and they cannot be revoked.

API keys

API keys are named tokens that do not expire and can be revoked as needed. To create a new API key, make sure you are in the Access tokens tab of the Preferences page, then select Create API key:

You'll see a required field for Token name, as well as an optional field for Token description:

When you click Create token, you will see a dialog with the new API key:

Warning: This is your only opportunity to see the key, so make sure to download or copy to a secure location!

After you close the dialog, you'll see your API key in the list, complete with name, date of creation, and description:

To revoke one or more API keys, select the boxes to the left of the tokens you wish to remove, then click Delete selected:

API keys can also be generated using the API, CLI, and Node.js and Python SDKs.

Application members

When an application needs to be shared with more than one user, the application owner can add new members. With paid accounts, it's possible to assign a level of access for a new member, based on the following types:

Member types

Owner

The application owner is the user who first creates an application. The owner is the only user who can add other application members or delete the application.

Observer

Observers are given read-only access to the application and its devices. They are not able to modify, add, or remove any devices, nor are they able to perform device actions. This role can only be assigned by application owners on paid plans.

Operator

Operators have all the access given to observers, plus the ability to manage an application's devices. This means operators can add new devices, remove devices, perform device actions, and modify device tags, metadata, and environment variables. Operators also have full SSH access to the application's devices. This role can only be assigned by application owners on paid plans.

Developer

Developers are given, in addition to the access provided to operators, the ability to manage an application. This includes pushing new code, modifying fleet-wide environment variables, running application actions, and downloading application images. This role is the closest to an application owner—developers can do everything owners can except for deleting the application or adding new members. The Developer role can be assigned by application owners on free or paid accounts, and it is the only role available for Starter applications.

Add an application member

To add a new member to your application, click on the Members tab of the application summary page:

This brings up a list of all application members, if any have been assigned. Click on the Add member button in the top left:

The Add application member dialog has a dropdown with descriptions of the member types, as well as information about which types are available based on your billing plan. Choose a level of access, then enter the username or email address of the new application member:

Note: Application members must have already signed up for a balena account before they can be added to an application.

After you click Add, you will see the username of the new application member in the list. From here, you can edit access levels or remove the user if necessary:

All users that have been added to an application will see that application in their dashboard, with an indicator to designate it has been shared by the application owner:

The shared application will also have a header with the application owner and the member's role:

In addition to the application actions permitted by the assigned member role, application members will have the option to remove themselves from an application. This is done by clicking the Actions tab from the application summary page, then clicking Remove Member Access:

Warning: If you remove your member access to an application, you will not be able to undo the action. Only the application owner will be able to restore your access.

Two Factor Authentication

We offer the option to enable Two Factor Authentication - this is a feature that prompts you to input a code from your smartphone/computer in addition to your password, providing an additional layer of security for your account.

Note: We use the industry standard Time-based One-time Password Algorithm to implement this functionality.

Enabling Two-Factor Authentication

Sign up for an account (or log in if you already have one) and go to your preferences page:-

Preferences Page

From here, click on the 'Two factor authentication' tab then click ENABLE to switch it on:-

Two Factor Authentication Tab, Disabled

Once you've enabled two factor authentication you will be given a QR code and prompted for a pairing code as shown below:-

Note: Two factor authentication will only be enabled once you have finished configuring it against your smartphone/computer, so no need to worry about logging out before finishing the configuration then not having access to your account!

Two Factor Authentication Tab, Configuring

In order to use your phone/computer as your added layer of security you will need to download a free authenticator application. There are many available, but one that works well and has been successfully tested against balena is Google Authenticator - download it for Android or iOS.

Once installed, navigate to the barcode scanner:-

Note: The Android application is shown here - if you already have accounts installed, tap the 3 vertical dots in the top right-hand corner and select 'Set up account', otherwise you should be given the option when you first start the app.

Google Authenticator Scan Barcode Menu

When you tap the option to scan a barcode your phone will turn on your camera and all you need to do to pair with your account is to simply point it at the QR code displayed on your monitor.

Once configured, you'll see a 6 digit generated code with a graphic beside it indicating a countdown. Once the countdown expires, the code becomes invalid:-

Google Authenticator Codes

Next you'll need to input the displayed code into the 'Pairing code' input on the preferences page.

Once you've paired your authenticator to your balena account you'll be all set up and the two factor authentication page will simply give you the option to disable it should you wish to later:-

Note: It's best to wait for the countdown to show plenty of time remaining before doing this as the window during which the code is valid is rather short!

Two Factor Authentication Tab, Enabled

Now when you log in you will be prompted for the code displayed in your authenticator app after you've input your username and password. Enjoy your added layer of security!

List of verified authenticator applications