Introduction

Welcome to the Tiled API!

You can use our API to enable single sign on (SSO) into our app.

More to come…

App SSO

HTTP based authentication

Example SSO universal link

https://app.tiled.co/app/sso/?
  url=https%3A%2F%2Fmy.auth.provider&
  apiToken=1234abcd5678efgh&
  usernameLabel=email&
  usernameKey=user.email&
  passwordKey=user.password&
  emailPath=user.profile.login&
  namePath=user.profile.firstName&
  namePath=user.profile.lastName&
  storeCredentials=true

For this example, and the username of bob@example.com and password of fancypants, the following will POST to https://my.auth.provider:

{
  "user": {
    "email": "bob@example.com",
    "password": "fancypants"
  }
}

The default POST body if usernameKey and passwordKey were not set would look like:

{
  "username": "bob@example.com",
  "password": "fancypants"
}

And we are expecting a JSON result of the form:

{
  "user": {
    "profile": {
      "login": "bob@example.com",
      "firstName": "Bob",
      "lastName": "Johnson"
    }
  }
}

You can see emailPath and the two namePath parameters will allow the app to correctly parse the result and extract bob@example.com as the email address to use for finding the correct tiled user in our system. The name parsed from this results would be Bob Johnson.

Use this method to authenticate with third party identity providers.

Universal Link

https://app.tiled.co/app/sso/

Query Parameters

Parameter	Required	Default	Description
url	true	none	The url for your identity provider’s authorization endpoint.
apiToken	true	none	Your Tiled API token - generated in account settings on https://app.tiled.co.
emailPath	true	none	The path to the user’s email address in the response body.
namePath	true	none	The path to the user’s name in the response body. If the user name is in multiple parts, they can be specified with multiple instances of namePath parameters and the results will be joined with a space at runtime.
expirationPath	false	null	The path to an optional session expiration date in the response body.
method	false	POST	HTTP method to use when accessing url.
usernameLabel	false	username	The placeholder text for the username form input in the app.
passwordLabel	false	password	The placeholder text for the password form input in the app.
usernameKey	false	username	The path in the request body to set the username in the request sent to url.
passwordKey	false	password	The path in the request body to set the password in the request sent to url.
ttl	false	null	How long the session should last (in milliseconds or a string representation e.g. “24h”, “30m”, “12345s”, “4d”). Note, if expirationPath is set and a valid date is found using it, ttl will not be used.
formTitle	false	Sign in	The title displayed at the top of the sign in form in the app.
formLogo	false	null	A URL to an image to display at the top of the sign in form in the app. The logo is letterboxed in a rectangle 306x80. Note - if set, formTitle will not be used.
primaryColor	false	#eb2227	The background color of the sign in button and the text color of the form inputs. Note, the sign in button text color is white.
storeCredentials	false	false	If this is true, the user’s credentials are stored in the device Keychain and when a session expires the user can authenticate with TouchID or 4-digit PIN to get a new session.

Web based authentication

Example SSO universal link

https://app.tiled.co/app/sso/?
  idp=fancypantsapp&
  ttl=24h

Use this method to authenticate with third party identity providers using a web-based OAuth, OpenID, SAML or other flow.

Universal Link

https://app.tiled.co/app/sso/

Query Parameters

Parameter	Required	Default	Description
id	true	none	A unique ID provided by Tiled
ttl	false	null	How long the session should last (in milliseconds or a string representation e.g. “24h”, “30m”, “12345s”, “4d”). Note - if ttl is not set, the session will not expire unless manually revoked on the Tiled website.

Using custom auth tokens

Example SSO universal link

https://app.tiled.co/app/auth/?
  idp=fancypantsapp&
  token=1234abcd5678efgh
  ttl=24h

Use this method if you want to generate and sign a secure token and send it directly into the app to authenticate the user.

Universal Link

https://app.tiled.co/app/sso/

Query Parameters

Parameter	Required	Default	Description
id	true	none	A unique ID provided by Tiled
token	true	none	A signed token containing the user’s email address for lookup
ttl	false	null	How long the session should last (in milliseconds or a string representation e.g. “24h”, “30m”, “12345s”, “4d”). Note - if ttl is not set, the session will not expire unless manually revoked on the Tiled website.

Custom Tiles with Remote Data

Overview

Custom tiles can be configured to fetch remote data for rendering. This documentation outlines the configuration values you can use and how they work.

Configuring remote URL

Example URL without query string parameters

// ENTERED URL
https://www.example.com/user/data

// REQUEST URL
https://www.example.com/user/data?
  userId=am9obmRvZUBleGFtcGxlLmNvbQ%3D%3D

You provide a URL where the data needed for the custom tile can be accessed. The URL will be access with an HTTP GET request with the current user’s ID appended as the query string parameter userId.

The user ID is their email address that has been base64 encoded.

Response

Example response

{
  "label": "My custom label",
  "body": "Some great body copy",
  "color": "#0080ff"
}

The URL you provide should return a valid JSON object with the Content-Type header set to application/json

The data you return will be used to override the default values (configurable in the app editor) for the custom tile.