Authorization

Productiv API uses OAuth to authenticate API requests. In order to use the API, Productiv will provide you with your OAuth credentials.

OAuth credentials use Client ID and Client Secret for authentication. The Client ID is issued to uniquely identify the client within an HTTP auth header. The Client Secret should be stored and securely passed into request headers.

Setup

The api credentials needed to query the developer APIs can be generated by going to the Organization settings page and clicking on New credential. This will allow you to create a new set of credentials with a name and a set of scopes. When the credential is created, it will display the Client ID and Client Secret. The Client Secret is shown only this one time, so make sure to save it somewhere.

Once you have your api credentials, you can use your Client ID and Client Secret to make a request for an access token. This is the token that you will use in every request to the developer APIs.

Access Token Endpoint

POST https://login.api.productiv.com/oauth2/token

Include the following headers and body parameters along with your requests:

Headers

Parameter	Value
content-type	application/x-www-form-urlencoded

Body Params

Parameter	Value	Description
grant_type	client_credentials
scope	`https://api.productiv.com/connector.write https://api.productiv.com/report.read`	One or more allowed scopes for the bearer token (space separated)
client_secret	<your customer specific client secret>	Provided on the Settings -> Organization page in Productiv
client_id	<your customer specific client id>	Provided on the Settings -> Organization page in Productiv

We support the following scopes while generating the bearer token. Each API may have different requirements for the required scopes to query that API.

Allowed Scope	Description
`https://api.productiv.com/connector.write`	Enables the client to write usage data to Productiv
`https://api.productiv.com/report.read`	Enables the client to query reports from Productiv
`https://api.productiv.com/apps.read`	Enables the client to read application data in Productiv
`https://api.productiv.com/apps.write`	Enables the client to write application data to Productiv
`https://api.productiv.com/elm.policy.read`	Enables the client to read ELM policies in Productiv
`https://api.productiv.com/elm.results.read`	Enables the client to read ELM results in Productiv

cURL Request Example

curl --location --request POST 'https://login.api.productiv.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=https://api.productiv.com/connector.write https://api.productiv.com/report.read' \
--data-urlencode 'client_id=<your_client_id_here>' \
--data-urlencode 'client_secret=<your_client_secret_here>'

Response

If the request is successful, a JSON response will be returned. This JSON object will contain the access token that can be used to make the API requests going forward and also the time until the access token expires.

The following response parameters will be returned:

Parameter	Description
access_token	The token you will use to make API requests.
token_type	The type of token that will be sent to make requests.
expires_in	Time in seconds until the access token expires. Once expired you can use this endpoint to generate a new access token.

Example Response Schema

{
  "access_token": "eyJraWQiOiJMUnB3MXVoZWE2Q2V3OGpGK1",
  "expires_in": 3600,
  "token_type": "Bearer"
}