Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Plugin Installation Flow

OAuth installation flow between TRMNL and your web server.

Plugin 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.)

  1. 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 code

  • installation_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 a playlist_item_id

  1. 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:

  1. 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):

  1. 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.

  1. 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