An account API key lets your own scripts, tools and home automation read and change your TRMNL account through our Account API. You choose what each key can do and which devices and plugin settings it can reach, and you can revoke any key without touching the others.
TRMNL has three kinds of credentials, so check this is the one you need:
Account API keys (this article) start with trmnl_. Use them for your own scripts and tools.
Developer apps are for apps other TRMNL owners connect to their own account. See Developer Apps.
Device API keys fetch one device's screen. Find yours on the device's settings page under Developer Perks.
Working from a terminal? The TRMNL CLI signs you in through your browser, no key needed.
Prerequisites
A TRMNL account with a device that has the Developer edition upgrade. Every BYOD license includes it.
Step 1 - Open the Developer section
Go to Account > Developer, or straight to trmnl.com/account/developer/edit. The Account API keys card appears once your account has a Developer edition device.
Step 2 - Create a key
Click New account API key and name it after the script or tool that will use it, so you know which key to revoke later. Then tick what it can do:
Read - read your devices and their logs, playlists, plugin settings and private plugin files
Content - change your markup, plugin settings, playlists and mashups, install recipes and push images
Devices - change your device settings and identify a device
Delete - delete plugin settings and playlist items, and clear a device playlist
Profile - see and change your name, time zone and display settings
Apps - install apps and manage them, including fleet pushes and room bookings
Tick only what the script needs. You can't add a capability to a key later, only create a new key.
Under Access control, keep Whole account (no limit), or pick Only specific devices and plugin settings to fence the key in. Then click Create account API key.
Step 3 - Copy the key
Your new key appears once, at the top of the Account API keys card. Copy it now. We keep only a fingerprint of it, so if you lose it, create a new key and revoke the old one.
Step 4 - Use it
Send the key in the Authorization header, with Bearer in front of it. This lists your devices, which needs the Read capability:
curl https://trmnl.com/api/devices \
-H "Authorization: Bearer trmnl_xxxxx"
Every endpoint is in our API docs. If a key lacks a capability an endpoint needs, the error names it.
Step 5 - You're done!
A key doesn't expire. It works until you revoke it. Each key on the card shows its capabilities, what it can reach and when it was last used.
Edit access changes which devices and plugin settings it reaches.
Revoke turns it off straight away.
The legacy account API key
Older accounts also have a Legacy account API key that starts with user_. It still works, but only on the endpoints it reached before keys had capabilities, and on nothing we've added since. For anything new, create an account API key.
Regenerate replaces the legacy key, and anything still using the old one stops working.
Troubleshooting
"Invalid API key". The key is wrong, revoked, or missing the word Bearer. The header must read Authorization: Bearer trmnl_xxxxx.
"This API key lacks the profile capability" (or another capability). The key wasn't given that permission, and capabilities can't be added later. Create a new key with it and revoke the old one. A common one: /api/me needs Profile, not Read.
"This API key was not granted" a device or plugin setting. The key is limited to others. Click Edit access beside it and widen it.
"This is a legacy API key". You're using the user_ key on an endpoint it never reached. Create an account API key.
"Rate limit exceeded". Requests are counted per minute across your whole account, every key and app together, and TRMNL+ accounts get a higher limit. The error says what the limit is. Wait a minute and try again.
There's no Account API keys card. It appears once your account has a device with the Developer edition upgrade.