User Access Tokens with Authorization Code Flow

The Authorization Code Flow allows a user to grant access to their resources on Tiltify for your application. This is a two step process that can be started by requesting the user's authorization.

1. Request Authorization

The first step requires that you send a user in a browser the the Tiltify OAuth Authorization url. You will include the following parameters in the url query:

Parameter	Value
client_id	required - The Client ID of your OAuth Application
response_type	required - The string "code"
redirect_uri	required - This should be the your Application's configured redirect_uri
scope	optional string of scopes. See supported scopes

info

The redirect_uri and scope parameters here must be URL encoded.

Example

Send the user to a url with the following query parameters. Note these examples are formatted for ease of reading.

Template Url

https://v5api.tiltify.com/oauth/authorize
    ?response_type=code
    &client_id=<client_id>
    &redirect_uri=<redirect_uri>
    &scope=<scopes>

When using the following values, note the url encoding:

• response_type: code
• client_id: 21ce85473de11b0abac192f354330284032ab4755925b58361dc08a4c34f62c7
• redirect_uri: http://localhost:9000
• scope: public

https://v5api.tiltify.com/oauth/authorize
  ?response_type=code
  &client_id=21ce85473de11b0abac192f354330284032ab4755925b58361dc08a4c34f62c7
  &redirect_uri=http%3A%2F%2Flocalhost%3A9000
  &scope=public

Full Url without formatting:

https://v5api.tiltify.com/oauth/authorize?client_id=21ce85473de11b0abac192f354330284032ab4755925b58361dc08a4c34f62c7&redirect_uri=http%3A%2F%2Flocalhost%3A9000&response_type=code&scope=public

If everything goes well, the user should be redirected to an authorization page:

2. Request Access Token

Once the user has authorized your application, they will be redirected back to your application with a query parameter of code. You will need this code in order to request a User Access Token.

http://localhost:9000/?code=8ed5ddf418ce0a5c878ee337882ccf434cc902853d90235fb86f31af3703e986

To generate a User Access Token, send a POST request to the /oauth/token endpoint of the Tiltify OAuth 2.0 Service with the following parameters encoded in application/json:

{
  "grant_type": "authorization_code",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "redirect_uri": "<redirect_uri>",
  "code": "<code>"
}

Example

cURL

curl -X POST https://v5api.tiltify.com/oauth/token \
   -H 'Content-Type: application/json' \
   -d '{"client_id":"e98e79be37f830026564ed5c190e01200c3f8f1707c4af36993c974e461dc64d","client_secret":"9e255194d71ab8594e665af33eb207e91cf122a00573b92d0f1965e0e4588f45", "grant_type": "authorization_code", "redirect_uri": "http://localhost:9000", "code": "8ed5ddf418ce0a5c878ee337882ccf434cc902853d90235fb86f31af3703e986"}'

If everything goes well, you should receive a successful response that looks like:

{
  "access_token": "36afa22dd518b023e79af8030874edffc20f580c4ea18f446918066e6e96abef",
  "created_at": "2023-04-17T19:40:02Z",
  "expires_in": 7200,
  "refresh_token": "2874fc249aaa498c9aad5ef776f6199d053741dde1e5dfd292babe4be1ecc2b4",
  "scope": "public",
  "token_type": "bearer"
}

You can now use your User Access Token to make requests to the Tiltify API.

Refreshing User Access Tokens

For security reasons, we do not provide infinite expiry Access Tokens. You will have to generate new Access Tokens when the provided ones expire

To do this, make a POST request to the /oauth/token endpoint with the following parameters encoded in application/json:

{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "grant_type": "refresh_token",
  "refresh_token": "<refresh_token>"
}

Example:

cURL

curl -X POST https://v5api.tiltify.com/oauth/token \
   -H 'Content-Type: application/json' \
   -d '{"client_id": "e98e79be37f830026564ed5c190e01200c3f8f1707c4af36993c974e461dc64d", "client_secret": "9e255194d71ab8594e665af33eb207e91cf122a00573b92d0f1965e0e4588f45", "refresh_token": njjjytm3otetmgrjmi00yjawlwe4zgytzjixy2mzm2y3njawcg121231999393a3"", "grant_type": "refresh_token"}'

If everything goes well, you should receive a successful response that looks like:

{
  "access_token": "7170707c3e0e719d96b88c20843ed8b66886375212e3b7658f9ae511ba05b38f",
  "created_at": "2023-04-17T18:16:48Z",
  "expires_in": 7200,
  "refresh_token": "e6e3c99ee2ebbfc97c082a88cda546d12f9f28505c0893b2b115e275f61018e9",
  "scope": "public",
  "token_type": "bearer"
}