The API uses the OpenAPI Specification (OAS) to define the API. More information about the OpenAPI Specification can be found at https://swagger.io/specification/.

Tiltify uses OAuth 2.0 access tokens to authenticate API requests. You may get an Application access_token or a User access_token. To authenticate, you will need to create an application in the Tiltify User Dashboard, and use the generated credentials.

The method to get an application access token follows the Client Credentials Oauth2 grant flow.

You may give the required parameters to the Oauth Token Endpoint to get an access token for use with the api directly.

The method to get a user access token follows the OAuth2 Authorization Grant flow. The following is a specific example of how to retrieve A User Access token using OAuth2

Getting the code

This example will be using the following values as needed.

• Application ID: 1234
• Redirect https://www.example.com/redirect
• Secret Key: asdf

To begin with, send a user in a browser to the Tiltify OAuth Authorization url. Include your Client ID, and the response type of code as query parameters. You may include your redirect URI if you have more than one. A space separated list of scopes may also be added, however, if not included, the public scope will be automatically selected.

https://v5api.tiltify.com/oauth/authorize?&client_id=1234&response_type=code&redirect_uri=https%3A%2F%2Fwww.example.com%2Fredirect&scope=public

After signing in and authorizing, the user will be redirected back to your chosen redirect URI with a query parameter of code, containing the code used to fetch the access token.

https://www.example.com/redirect?code=1234abcdef

The code should be passed to your server backend as the following steps require your secret key, which should not be exposed to the public.

Converting The Code To A User Access Token

To retrieve the User Access Token, a post request must be made to the Token URL. In the body of the url are the following fields in Form Data format. Note specifically that code is the code retrieved from the first step.

client_id=1234
redirect_uri=https://www.example.com/redirect
code=1234abcdef
grant_type=authorization_code

Tiltify will return a response like the following:

{

    "access_token": "ab6a592346444dea97170837e104d8a5ab6a592346444dea97170837e104d8a5",
    "created_at": "2023-01-27T19:32:03Z",
    "expires_in": 7200,
    "refresh_token": "njjjytm3otetmgrjmi00yjawlwe4zgytzjixy2mzm2y3njawcg121231999393a3",
    "scope": "public",
    "token_type": "bearer"

}

This access token may now be used as shown below to make requests. When used with the /current-user endpoint, the full user object is returned.

Add the Authorization header to your HTTP request.

Authorization: Bearer <access_token>

Example:

Authorization: Bearer ab6a592346444dea97170837e104d8a5ab6a592346444dea97170837e104d8a5

When an initial access token is created, a refresh token will be provided. The refresh token can be used to get a new access token when the current one expires. To do this, make a post request to the token url with grant_type set to refresh_token.

Example:

To refresh the User Access Token, a post request must be made to the Token URL. In the body of the url are the following fields in Form Data or json format.

client_id=1234
client_secret=asdf
grant_type=refresh_token
refresh_token=njjjytm3otetmgrjmi00yjawlwe4zgytzjixy2mzm2y3njawcg121231999393a3

Tiltify provides a dashboard to subscribe and test campaign and campaign donation webhooks.

To register a webhook, visit the Developer Dashboard

In order to begin registering webhooks, you must first create an application.

In the application dashboard, there will be a side navigation option for Webhooks.

• Click the Add Webhook button
• Create the webhook with an endpoint URL and an optional description.
• Click edit on the newly created webhook
• Click the Events submenu and add and event to subscribe to using the Add event button.
• Enter your Campaign ID, this can be found in your campaign's dashboard under Setup > Information
• Once created, click the ... button and select Edit
• Select the donation and/or Campaign events you would like to receive to your webhook endpoint and click Update Event. Including private data may include sensitive information, so please ensure that you secure your application.

You should now receive updates for those events on your webhook url.

Caution: When we send a webhook we expect the endpoint to respond with a 200-299 status code. If we do not receive that, we deactivate the webhook after about an hour.

Once a webhook is created, you may send test messages through the Testing Submenu.

An example payload will be shown for each event type.

Click Send Test to initiate the test.

OAuth 2.0 endpoints

Team Campaign endpoints

Cause endpoints

Campaign endpoints