A web app that demonstrates embedding Applets with the IFTTT API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

IFTTT API Example

The IFTTT API makes it easy for services to embed Applets into websites and mobile apps. This repository contains an example web app written in Ruby that demonstrates how to use the API with a simple service. It has no triggers or actions, and its authentication system is passwordless. You can view it live here.

Note that this example is a bit more complicated than a real integration, because it’s also acting as a complete IFTTT service. You’ll be able to leverage your existing IFTTT service and your website or app’s existing auth system. However, it does illustrate how to integrate the IFTTT API into a server-side app.

Web UI

Listing Applets:

The home page of the example app uses WebUIController#root and IftttApi#list_applets to send a request to the List Applets endpoint and displays the Applets returned using the views/index.erb template.

Activating Applets:

You won’t be logged in when you first visit the page, so the user_status for Applets will be nil and you’ll see a Activate button for each Applet. If you click the Activate button, you’ll be taken through the IFTTT web UI as described in the Activating an Applet documentation. In short, you’ll visit a URL like https://ifttt.com/embed/SERVICE_ID/applets/APPLET_ID which will redirect you back to your app once activation is complete.

Logging In:

To log into the example app, click the Log in button in the bottom right. You won’t be asked for a password. Simply provide any username you like and WebUIController#log_in will save a user record and store the username in the session. The example app saves the username you provide and uses that to authenticate with the IFTTT API using the Service-authenticated scheme. The combination of the IFTTT-Service-Key header and user_id param allows IFTTT to authenticate the user within the context of the example app for the purpose of enabling and disabling Applets that have been configured previously. For other actions, we’ll use the User-authenticated scheme, which is covered below.

Enabling and Disabling Applets:

If you’ve activated an Applet once, you’ll be able to enable or disable it with a single click as long as you’re logged in to the example app. The enable action uses WebUIController#enable and IftttApi#enable_applet to send a request to the Enable an Applet API endpoint. The disable action uses WebUIController#disable and IftttApi#disable_applet to send a request to the Disable an Applet API endpoint.

Mobile API

In conjunction with the IFTTT API, IFTTT provides SDKs for iOS and Android which include wrappers and data models for the various API endpoints. For security reasons, authenticated requests to the IFTTT API issued from mobile apps must use the User-authenticated scheme, which requires an IFTTT user token header. You should fetch these tokens on your backend service using the Get a user token API once your service has issued an OAuth token to IFTTT.

Get a mobile token

To start, we’ll use MobileAPIController#log_in to generate an example_app_token which we’ll use to log into the example app. Note that this token is distinct from the user_token, which is generated by IFTTT and used exclusively for making User-authenticated requests to the IFTTT API. Since we’re using a passwordless authentication system, simply sending a username will suffice:

curl -X POST http://ifttt-api-example.herokuapp.com/mobile_api/log_in \
  -d "username=example"

{
  "token":"f42c5430d013ad1ab40199598feeb19ed9e3b0c0"
}

Automatically log in and redirect to the Applet

Once we have the example_app_token we can request a URL using MobileAPIController#get_login_url that will automatically log the user into the example app and redirect to an Applet page. This way, when it comes time for the IFTTT service connection, the user does not then need to sign into their account, but is instead sent straight to the OAuth authorization page.

For the redirect_to URL, we recommend including email and user_id parameters to streamline the login process. You can read more about these parameters in the Authentication section of the API documentation. (Make sure any special characters in the email are percent-encoded; for example, @ should be encoded as %40 and + should be encoded as %2B.) You’ll also want to include a redirect_uri, which is the URL you want the user to end up at once they’re done with the entire configuration flow. In the case of a mobile app, this might be a link your app will recognize and handle natively. The redirect_uri has to be on the list of allowed URIs located on the Redirects page in your service’s settings.

Finally, note that an invite_code parameter is required if your service isn’t published yet. You can find the invite code on the General page in your service’s settings. Look for the code param in the Invite URL field.

curl -X POST http://ifttt-api-example.herokuapp.com/mobile_api/get_login_url \
  -d "redirect_to=https://ifttt.com/embed/ifttt_api_example/applets/m9PaKBvR?email=user@example.com&user_id=example&redirect_uri=http://ifttt-api-example.herokuapp.com" \
  -H "Authorization: Bearer f42c5430d013ad1ab40199598feeb19ed9e3b0c0"

{
  "login_url":"http://ifttt-api-example.herokuapp.com/authorize?token=..."
}

Get an IFTTT user token

To make requests from a mobile app to the IFTTT API authenticated as an example app user, we’ll need an IFTTT user token, which we can get by using MobileAPIController#get_user_token and IftttApi#get_user_token to send a request to the Get a user token endpoint.

curl -X POST http://ifttt-api-example.herokuapp.com/mobile_api/get_ifttt_token \
  -H "Authorization: Bearer f42c5430d013ad1ab40199598feeb19ed9e3b0c0"

{
  "token":"ihaP2fDW8cvmXJ7Pjr7_YxAyHkgxqL-PYUmPyu_r38KmCx7e"
}

Note if the response is {"token":null} that means the user in the example app has no oauth_token which means that the user hasn’t connected the service to IFTTT. If you’re debugging, you can connect the service from the IFTTT API Example service page manually.

Make a User-authenticated request to the IFTTT API

Once you have an IFTTT user token, you can make requests to the IFTTT API that are authenticated as a user within the context of the example service.

curl https://api.ifttt.com/v1/me \
  -H "Authorization: Bearer ihaP2fDW8cvmXJ7Pjr7_YxAyHkgxqL-PYUmPyu_r38KmCx7e"

{
    "authentication_level": "user",
    "service_id": "ifttt_api_example",
    "type": "me",
    "user_login": "example"
}

OAuth and IFTTT Protocol support

Note that this example app contains barebones support for both OAuth and the IFTTT Protocol. The OAuth code is contained in WebUIController#oauth/authorize and WebUIController#oauth/token and is necessary for responding to the IFTTT server’s request to exchange an authorization code for an access token, according to the OAuth 2.0 spec. The IFTTT Protocol code is contained in IFTTTProtocolController and is necessary because use of the IFTTT API requires at least a minimally connectable service.