TRMNL API
HomeBuy a Device
  • 👋Overview
  • How it Works
  • Private Plugins
    • Screen Templating
    • Screen Templating (Graphics)
    • Create a screen
  • DIY TRMNL (Advanced)
    • Introduction
    • BYOD
    • BYOD/S
    • BYOS
  • ImageMagick Guide
  • Plugin Marketplace
    • Introduction
    • Plugin Creation
    • Plugin Installation Flow
    • Plugin Management Flow
    • Plugin Screen Generation Flow
    • Plugin Uninstallation Flow
    • Going Live
  • Private API
    • Introduction
    • Fetch Screen Content
    • Fetch Plugin Content
    • Account API
  • Partners API
    • Introduction
    • Getting Started
    • Provisioning Devices
Powered by GitBook
On this page
  1. Plugin Marketplace

Plugin Installation Flow

OAuth installation flow between TRMNL and your web server.

PreviousPlugin CreationNextPlugin Management Flow

Last updated 2 months ago

  1. Installation Request

When the user installs your plugin, TRMNL sends an installation request to installation_url with unique token and installation_callback_url.

  1. Fetch Access Token

After receiving the request, Your server using the client_id, client_secret and token from step#1 request the access_token from TRMNL using the following endpoint:

body = {
  code: 'code-from-step-1',
  client_id: 'your-plugin-client-id',
  client_secret: 'your-plugin-secret',
  grant_type: 'authorization_code'
}
response = HTTParty.post("https://usetrmnl.com/oauth/token", body: body)
response['access_token']
  1. Access Token

TRMNL responds with the access_token.

  1. Installation Callback

Use the installation_callback_url from Step #1 and redirect the user back to TRMNL.

  1. Success Webhook

After the user has successfully finished installing the plugin, TRMNL sends a success notification to installation_success_webhook_url endpoint. Data is sent in JSON format as follows.

HTTP Headers:

{ 'Authorization': 'Bearer <access_token>', 'Content-Type': 'application/json' }

Body:

{
  "user": {
    "name":"Ronak J",
    "email":"ronak@usetrmnl.com",
    "first_name":"Ronak",
    "last_name":"J",
    "locale":"en",
    "time_zone":"Pacific Time (US & Canada)",
    "time_zone_iana":"America/Los_Angeles",
    "utc_offset":-28800,
    "plugin_setting_id":1234,
    "uuid": "674c9d99-cea1-4e52-9025-9efbe0e30901"
  }
}

The plugin_setting_idis useful for building a redirect URI in your own application, for example to send a user back to usetrmnl.com/plugin_settings/:plugin_setting_id/edit.

Time zone mappings are available here under "Constants:"

https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html