To actively use the Tive Public API, you will first need a client ID and secret. The client ID is a public identifier of your application, while the client secret is confidential and should only be used to authenticate your application when generating API Bearer Tokens.

Your client secret and bearer token will grant certain privileges within Tive, so be sure to keep them secure. Never share either in publicly accessible areas such as Bitbucket, Github, or client side code.

Generate Your Client ID and Secret

To generate new credentials for Tive's public API, open the User menu on the top right corner of the Platform and select Organization. Next, navigate to the API tab and click Add New Credentials. Note that the Organization menu item is restricted to Admin users. If you are not an Admin, contact one from your team who can upgrade your permissions.

When creating a new integration you will need to provide the following information:

• Client ID: A unique name for your API integration.
• Account: Associate the account(s) you would like the integration to work for.
• Description: An optional description of what the integration is used for.

Once generated, you will be able to copy your client secret:

Please note that this will the only time you will be able to view your client secret, so make sure to copy it and save it in a secure location. If you lose your secret or need to generate a new one, please repeat the process outlined above.

API Bearer Tokens

Tive utilizes Bearer Tokens for authentication against our public endpoints. Valid bearer tokens must be sent in the Authorization header when making requests to Tive. The general format for specifiying a token in a request looks like this:

curl -X GET 'https://api.tive.com/public/v3/<endpoint>' -H 'Authorization: Bearer TOKEN'

Generating a Bearer Token

Once you have your client ID and secret, next you will need a valid bearer token to use in the header of your requests. To do so you will need to make a POST request to the authenticate endpoint:

curl -X 'POST' \
  'https://api.tive.com/public/v3/authenticate' \
  -H 'accept: text/plain' \
  -H 'Content-Type: multipart/form-data' \
  -F 'client_id=your-client-id' \
  -F 'client_secret=your-client-secret' \
  -F 'grant_type=client_credentials'

The response of this request will return a valid token for you to use as well as the amount of time, in seconds, until the token expires. Tokens are currently set to have a lifetime of 1 hour.

{
  "token": "YOUR-TOKEN",
  "token_type": "Bearer",
  "expires": "3600"
}

Once a token expires you will need to repeat the request above and make sure the Authorization header has been properly updated. Otherwise, Tive will send the following 401 error response:

content-length: 0 
date: Wed,17 Aug 2022 18:49:00 GMT 
www-authenticate: Bearer error="invalid_token",error_description="The token expired at '08/17/2022 18:48:35'" 

If you would like to use your token to test endpoints out as part of our API Reference Section, paste the value into the OAuth2 field found on the top right of the endpoint you would like to test. Once pasted, this value will persist as you navigate to other endpoints.