This article was originally published on 03/2018 and has been updated on 08/2022 to add key versions.
What are users API keys ?
Any BrandMeister user can generate an API key. A key is a long string of characters that is unique to a Brandmeister user account. This digital key allows a third-party application to read and update the data on the corresponding Brandmeister Account (such as your list of hotspots, repeaters, your static talkgroups, etc.).
API keys were first introduced in Brandmeister in 2018, as API v1. In August 2022, developers improved the API features and created API v2, which changed the keys format. API keys created after 2022/08/19 are in v2 format. Keys created prior to this date are in v1 format.
Will API v1 be retired?
To ensure a smooth transition, API v1 keys created prior to 2022/08/19 will still be working for several months. They are no longer visible in the user’s self-care account, but they are still active.
While there is no set date for retiring API v1, we strongly encourage everyone to upgrade their keys to API v2 as soon as possible.
What does an API key look like?
An API v1 key is a 128-character string. For example:
MWaztB3EcHWBEW@D$2gb89Y2kvvE4leSr.33Gey74d0IYVSKU58YGMSFmPHD.Q1fECUkIcj7E4leSr.33Getkjshdf987ywe2irligr908SFIdlsfkj08934sasdlveg
The most recent API v2 key is a longer character string known as a JSON Web Token. For example:
jh7KJSAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwianRpIjoiOWVjYjBhODRmYTAwODdkNjQ2YmNmNWJlMGJjMGEyZDQ0YmUxNGFkNDllNmM5OWNhM2NkNTcyNjViOGNjYjJmN2ZlNThlYzI1MjNhZWM2YTQiLCJpYXQiOjE2NjA5MzI0NjIuMDI5NzEyLCJuYmYiOjE2NjA5MzI0NjIuMDI5NzE1LCJleHAiOjQ4MTY2MDYwNjIuMDA3OTIyLCJzdWIiOiIxOTIiLCJzY29wZXMiOltdfQ.PnoQ3LkPeuV1TW1Hggn-D7Lloq3TRIB0bHEXTC3Ck1zXDqJRXvjf74sSJ01RSCDCOEAzyDW8eYDjguswGOjMmJ3Lp0IPAcSU7yZY3cjz7NNuFbiqllyV_jXYoBybU-FzSEuoEl3Nx6kbO6iNb_IoDrdloRxVtEDsQJ8Q27FouzMcf3lSxriwmC3tVv2V5phqzJlT-DyL0QLgZaRyDnRdxJtq6yLW5EPUAK6uAHRANCs_wbeSAKVZmqC6ycLJ0ZfIvbUBr7312HP8u2kInh1vcpnNczWyoc7FsjcZjBYrMskt7zRds051a_KqoP8uzUUSS9ZZSxrd_KDozUQ6CiWSB7nCc96B4KLY4CCpJq50I1RSnxrg4Pamj8b8abdO6O5yGakUDrp0t1jMONhOb_B9SlyNgy55SxY2ZC0Q9h3MNC1fxw_rKd73wWjD1SWsW2SI1iaAZA6ewLbn5xPpHvUlVtNri0ZO2oPfdn_1nRImCAwlYKt4LbUKmAFp-vgshMknVlVwutDNQ815y9M3F994Za_OghmAylUaWDextUh6Kx4eYAZuNnB6OphDwS08dWUZOe7MEMBH1OM2Sw_GbbjGPiS82pUDqPZzkfjs5ghFS1CfAu1BB8Teh0wgLqevWaN7VLJWOSSgl9-IOAdSSphmH0yprWbuZHPNyWq1HDY_eEI
Why using an API key?
You can enter your API key in a third-party software or hardware appliance to read and manage the information within your Brandmeister account (including repeaters, hotspots, talkgroups configuration, etc.). Using an API key allows you to keep your SelfCare username and password confidential and to have granular control over each key you provide to others.
The API key is completely unrelated to your SelfCare password. If you change your SelfCare password, the keys you have generated are still valid.
At any time you can Revoke a key, and any person or application with this key will no longer be able to access the information and features of your Brandmeister account.
How to generate and revoke my user API keys?
To generate an API key, follow these steps:
- Login to your BrandMeister SelfCare account using a web browser, and authenticate using your callsign and password.
- Click on your callsign or avatar at the top of the screen, and select “Profile Settings”
- Click on the “API Keys” button in the Security Settings section
- This is where your existing keys (if any) will be displayed. Click “Add” to create a new key.
- Provide a name for your API key.
You can create as many keys as you’d like. It is therefore recommended to generate one key per application you will use, and name the key accordingly. The name has no impact on the key, it is just a label utilized in the SelfCare to help you remember which key is which.
- The next screen will display the API key. If you are using a mobile app, chances are that you can just take a photo of the key within the app and you are done. Otherwise you may copy/paste the key into the application directly.
This is the only time the key code and barcode will be visible. Once you click “OK” only the key name will be available in your list. There is no need to keep a copy of your key somewhere, considering that you can always revoke and generate a new key.
BE EXTREMELY CAREFUL TO WHOM YOU GIVE YOUR KEY TO, AND WHERE YOU SAVE YOUR KEY. THE KEYS ALLOW A COMPLETE AND FULL ACCESS TO ALL THE FEATURES OF YOUR PERSONAL SELF-CARE. THIS INCLUDES REPEATER/MASTER SYSOP FUNCTIONS!
- After clicking “OK” you will be sent back to the list of API keys, with the ability to revoke a key if needed.
Why not just provide my SelfCare account credentials?
Your password is confidential and should never be given to others. Providing a separate key to each third-party allow you better control: if you provided your account password, each time you want to change the password you will have to go back to each third party to update it. With the API keys, you can change your SelfCare account password or revoke a key without affecting all other keys you have already provided.
Are there any existing applications using user API keys?
There are currently three developers we have worked with to develop the first applications leveraging user API keys:
Pi-Star is a custom, pre-configured SD Card image for the Raspberry Pi, built on Raspbian Linux. It includes software stacks by G4KLX, MMDVMHost / DStarRepeater, and associated tools & programs.
Its built-in dashboard now includes the ability to make changes to users’ BrandMeister configuration, by leveraging the use of APIs.
Documentation
Repeater Reader is a small JAVA program that creates visibility and management options for the selected repeater or hotspot. It will also get support for controlling the repeater through APIs.
The BrandMeister team wishes to thank all application developers for making all of this happen!
