Skip to content
API References
/
/
Request access token

Auth (1.0.0)

This API allows you to request authentication tokens. You can also use it to generate secure URLs that are used in granting customer access to the Tilia services.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://lindenlab.com
Tilia, Inc.
tilia@lindenlab.com
License
Tilia, Inc.
Languages
Servers
Mock server
https://thunes-tilia-docs.redocly.app/_mock/openapi/prod/auth/openapi/
https://auth.staging.tilia-inc.com/

Request access token

Request

An Access Token is a string that enables Tilia to verify that a request belongs to an authorized session. Requesting an access token requires the client ID and secret you obtained when registering as a Tilia integrator. The returned token can then be used to to make API calls.

Bodyapplication/x-www-form-urlencoded
client_idstring(UUID4)required

Your Tilia client ID.

Example: "3f2bfe5b-19b8-41c1-88d7-70a1586bce94"
client_secretstring(UUID4)required

Your Tilia client secret.

Example: "9bc00ca4-937e-4946-bdb5-0814b603334d"
grant_typestringrequired

The type of token you're requesting. Must have a value of client_credentials.

Example: "client_credentials"
scopeArray of stringsrequired

The scopes for the token. Refer to the documentation of the endpoint you are calling for the required scope(s).

Example: ["write_registrations,write_user_tokens,user_info"]
curl -i -X POST \
  https://thunes-tilia-docs.redocly.app/_mock/openapi/prod/auth/openapi/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=3f2bfe5b-19b8-41c1-88d7-70a1586bce94 \
  -d client_secret=9bc00ca4-937e-4946-bdb5-0814b603334d \
  -d grant_type=client_credentials \
  -d 'scope=write_registrations,write_user_tokens,user_info'

Responses

Success.

Bodyapplication/json
access_tokenstring

The Tilia access token.

Example: "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiIiwiY2xpZW50X2lkIjoiMDRhZmJlMTctY2RlNi00OTlkLThlMTctZGExZjgwNmU3YzRkIiwiZXhwIjoxNjAwNTY0NTc2LCJpYXQiOjE2MDA1NjA5NzYsImludGVncmF0b3IiOiJ1cGxhbmQiLCJqdGkiOiIxM2Y1NDQ1Mi1kMTI4LTRmZDItODc0Ny01ZmI4NWEwYjQwZWUiLCJuYmYiOjAsInNjb3BlcyI6WyJkZWxldGVfd2FsbGV0IiwiY3JlYXRlX25vbmNlIiwicmVhZF9ub25jZSIsImRlbGV0ZV9ub25jZSIsInJlYWRfcGF5bWVudF9tZXRob2RzIiwid3JpdGVfcmVnaXN0cmF0aW9ucyIsIndyaXRlX3VzZXJfdG9rZW5zIiwidXNlcl9pbmZvIiwid3JpdGVfaW52b2ljZXMiLCJyZWFkX2t5Y3MiLCJ3cml0ZV9yZWdpc3RyYXRpb25fcHJvdmlkZXJfZGF0YSIsInNlYXJjaF9hY2NvdW50cyIsImNoYW5nZV9hY2NvdW50cyIsImJsb2NrX2FjY291bnRzIiwiY3JlYXRlX3dhbGxldCIsInJlYWRfaW52b2ljZXMiLCJyZWFkX3dhbGxldCIsIndyaXRlX3Byb2Nlc3NfY3JlZGl0cyIsInJlYWRfcHJvY2Vzc19jcmVkaXRzIl0sInRva2VuX3R5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJ1c2VybmFtZSI6IiJ9.WQo3tl1zHC2CJCJjohONiCtaPXbgnvpOqCV0Bv4sxubYiNuIa9J8j9BKTagdbd3kLHnKJLzW083mdR3UzPQbOSvBv0yzZDd-pjAnD5D0GF4y49ZOFLb2Kl_qy2c-66-D9BAS1ilwATHTiWtBcHzfh7VfTu-w9Fs3RLCHchsP0ioPsOcWzJ1BmkeuYwxXVYeaGE8vL5z26BGovFOC_SAl-V3UQFq_PnwNsame_ksKus6ayXahAXOkDyTXJkCxHHkc-08VW-JZyWWq0tQkdvZ7_H9CTThFQQ_ByCmVF9bhmf"
token_typestring

The token type. (e.g. Bearer)

Example: "Bearer"
expires_instring

The token expiration time, in seconds.

Example: "3600"
scopestring

The requested scope(s).

Example: "write_registrations,write_user_tokens,user_info"
Response
application/json
{
  "access_token": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiIiwiY2xpZW50X2lkIjoiMDRhZmJlMTctY2RlNi00OTlkLThlMTctZGExZjgwNmU3YzRkIiwiZXhwIjoxNjAwNTY0NTc2LCJpYXQiOjE2MDA1NjA5NzYsImludGVncmF0b3IiOiJ1cGxhbmQiLCJqdGkiOiIxM2Y1NDQ1Mi1kMTI4LTRmZDItODc0Ny01ZmI4NWEwYjQwZWUiLCJuYmYiOjAsInNjb3BlcyI6WyJkZWxldGVfd2FsbGV0IiwiY3JlYXRlX25vbmNlIiwicmVhZF9ub25jZSIsImRlbGV0ZV9ub25jZSIsInJlYWRfcGF5bWVudF9tZXRob2RzIiwid3JpdGVfcmVnaXN0cmF0aW9ucyIsIndyaXRlX3VzZXJfdG9rZW5zIiwidXNlcl9pbmZvIiwid3JpdGVfaW52b2ljZXMiLCJyZWFkX2t5Y3MiLCJ3cml0ZV9yZWdpc3RyYXRpb25fcHJvdmlkZXJfZGF0YSIsInNlYXJjaF9hY2NvdW50cyIsImNoYW5nZV9hY2NvdW50cyIsImJsb2NrX2FjY291bnRzIiwiY3JlYXRlX3dhbGxldCIsInJlYWRfaW52b2ljZXMiLCJyZWFkX3dhbGxldCIsIndyaXRlX3Byb2Nlc3NfY3JlZGl0cyIsInJlYWRfcHJvY2Vzc19jcmVkaXRzIl0sInRva2VuX3R5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJ1c2VybmFtZSI6IiJ9.WQo3tl1zHC2CJCJjohONiCtaPXbgnvpOqCV0Bv4sxubYiNuIa9J8j9BKTagdbd3kLHnKJLzW083mdR3UzPQbOSvBv0yzZDd-pjAnD5D0GF4y49ZOFLb2Kl_qy2c-66-D9BAS1ilwATHTiWtBcHzfh7VfTu-w9Fs3RLCHchsP0ioPsOcWzJ1BmkeuYwxXVYeaGE8vL5z26BGovFOC_SAl-V3UQFq_PnwNsame_ksKus6ayXahAXOkDyTXJkCxHHkc-08VW-JZyWWq0tQkdvZ7_H9CTThFQQ_ByCmVF9bhmf",
  "token_type": "Bearer",
  "expires_in": "3600",
  "scope": "write_registrations,write_user_tokens,user_info"
}

Request client redirect URL or password token

Request

By default, generates a temporary page that allows a user to visit and have a browser session set. This is typically the first step in directing the user to a Tilia web UI, such as those presented in the payments or payouts flows. After calling this endpoint, redirect the client's browser to the URL in the response payload. More info about the web UI can be found here.

Alternatively, if return_token is set to true, the response payload will contain the key token whose value is a password token string that can be passed directly to other API calls. This is useful for clients that are not browser-based.

Security
tilia_auth
Bodyapplication/json
account_idstring<= 36 charactersrequired
Example: "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b"
return_tokenboolean

If true, a Tilia oauth token will be returned in the response payload rather than a URL redirect. Defaults to false.

mechanismstring

JWT created for the account_id supplied in the request body. NOTE: this only works if the mechanism is tilia_hosted.

Example: "tilia_hosted"
flowstring

Indicates which pub hosting flow to use. NOTE: this only works if the mechanism is tilia_hosted.

Example: "addcard"
token_expiration_secondsstring

An optional field indicating how long, in seconds, the token lastes

Example: 30
curl -i -X POST \
  https://thunes-tilia-docs.redocly.app/_mock/openapi/prod/auth/openapi/authorize/user \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b",
    "return_token": true,
    "mechanism": "tilia_hosted",
    "flow": "addcard",
    "token_expiration_seconds": 30
  }'

Responses

Success.

Bodyapplication/json
statusstring

The status of the request, either Success or Failure.

Example: "Success"
messageArray of strings

An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.

Example: [null]
codesArray of strings

An array of failure reason codes. If the request was successful, this array will be empty.

Example: [null]
payloadobject
Response
application/json
{
  "status": "Success",
  "message": [
    null
  ],
  "codes": [
    null
  ],
  "payload": {
    "nonce_auth_id": "80b4ff4b-320c-49b3-addf-b8e2e9b13b8c",
    "redirect": "https://web.tilia-inc.com/ui/appauth/80b4ff4b-320c-49b3-addf-b8e2e9b13b8c",
    "token": "string"
  }
}