Plugin Installation Flow
OAuth installation flow between TRMNL and your web server.
Third Party plugins use a simplified OAuth2 flow. The token exchange needs no client_id or client_secret -- TRMNL identifies your plugin by the URLs you registered during Plugin Creation, and each installation is authorized by a code. (Your Client ID does matter later, to verify the management flow JWT.)
Installation Request
When a user installs your plugin, TRMNL redirects their browser to your installation_url. This is a GET request, so both parameters arrive in the query string (URL-encoded):
code— an installation code for this user + plugin. If the user abandons the flow and starts again, they arrive with the same codeinstallation_callback_url— the TRMNL URL you send the user back to once installation is complete (see Step 4). Treat it as opaque -- it may carry extra params, like aplaylist_item_id
Fetch Access Token
Exchange the code from Step 1 for an access_token by sending a POST request to TRMNL's token endpoint. The code is the only parameter required, sent as a form-encoded body:
Access Token
TRMNL responds with a JSON body containing the access_token. Persist this token -- TRMNL sends it as the Bearer token on every screen generation request and webhook, so you can match each request to this installation. The token doesn't expire and there's no refresh step. Exchanging the same code again returns the same token.
If the code is missing or invalid, TRMNL responds with an error body instead (note: the HTTP status is still 200):
Installation Callback
Redirect the user's browser to the installation_callback_url you received in Step 1. This GET redirect returns them to TRMNL's new plugin instance form, where they can name the instance, then click Save. The installation isn't complete until they save.
Success Webhook
When the user clicks Save in Step 4, TRMNL sends a POST request to your installation_success_webhook_url. The request is authenticated with the user's access_token and the body is JSON. We send it once, with no retries.
HTTP Headers:
Body:
Time zone mappings are available here under "Constants:" https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html
The plugin_setting_idis useful for building a redirect URI in your own application, for example to send a user back to trmnl.com/plugin_settings/:plugin_setting_id/edit.
Last updated