API Authorization

Authorization methods and principles used to access the Knowde APIs.

The Knowde API uses OAuth 2.0 to authorize requests to the API.

Authorization overview

To authorize your application:

1. Create an API Client.
2. Request an access token using an authorization flow.
3. (If you received a refresh token in 2.) Request further access tokens using the refresh token flow.

Creating an API Client

You can use the Developer Portal to create an API Client.

Requesting an access token

To request an access token from the OAuth 2.0 service, use the following host:

https://developer-api.knowde.com

The Authorization API provides the following Authorization flows:

• Client credentials: Creates a token for an API Client.

Client Credentials Flow

To obtain an access token through the client credentials flow, just issue the following request to the auth service.

POST https://{auth_host}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Example Request:

$curl https://{auth_host}/oauth/token -X POST \
  --basic --user "{clientId}:{clientSecret}" \
  -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"

Example Response:

{
  "access_token": "zW8wwPOTAOT0J0Robyf-bwpWtuCTWWHOfWHt8vaA0d4",
  "refresh_token": "IHrE3eR-m2UbZjpSR8d9Yw-PHTddZkaCmrGC3BBgNQM",
  "expires_in": 86400, // seconds (1 days)
  "created_at": "2023-04-18 20:17:13 UTC",
  "token_type": "Bearer"
}

Parameters are provided using the application/x-www-form-urlencoded media type.

Refresh Token Flow

To obtain an access token through the refresh token flow, issue a request to the token endpoint with your client credentials and include the refresh token you received previously.

POST https://{auth_host}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}

Example Request:

$curl https://{auth_host}/oauth/token -X POST \
  --basic --user "{clientId}:{clientSecret}" \
  -d "grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN"

Example Response:

{
  "access_token": "8WJEYI6X6d7KIU-eBN7HPw2MBuOLWfJvATHAz9KLO8o",
  "refresh_token": "45vqzS2bHlh8B1b8V1VifbPP3umJZVyxzxp9kzL286s",
  "expires_in": 86400, // seconds (1 days)
  "created_at": "2023-04-18 20:17:13 UTC",
  "token_type": "Bearer"
}

Parameters are provided using the application/x-www-form-urlencoded media type.

Using an access token

Upon successful completion of an authorization flow, the OAuth 2.0 service returns an access_token.

Use the access token in the Authorization header of all requests to the Knowde API as follows:

GET /lead_groups HTTP/1.1
Host: https://developer-api.knowde.com
Authorization: Bearer {access_token}

...

The Knowde API does not support sending access tokens as URI parameters, as defined in RFC 6750 section 2.3.

The remaining lifetime of an access token is indicated by its expires_in field.

Managing token requests

For security reasons, we advise requesting tokens sparingly and keeping the number of active tokens to a minimum whenever possible.

We do not recommend requesting a token for every work item. If a client application requests too many tokens, it might be rate-limited.

We recommend getting new tokens when appropriate using automatic token management.

Revoking tokens

The Knowde API authorization service implements Auth 2.0 Token Revocation under /oauth/revoke. This endpoint provides a mechanism to invalidate access and refresh tokens within the authorization server. This behavior prevents the abuse of abandoned tokens and should probably only be done if you need to invalidate a token for security reasons.

Only tokens that were issued to the client making the revocation request are allowed to be revoked by the client. To revoke a token, it is necessary to provide the client_id and client_secret as a Base64 encoded Basic Authorization that was used to generate the token. Parameters are provided using the application/x-www-form-urlencoded media type.

Example Request

curl -F token={token} \
  -H "Authorization: Basic Base64(client_id:client_secret)" \
  -X POST https://developer-api.knowde.com/oauth/revoke

Response

The endpoint will always return a 200 OK, even if token doesn't exist or has already been revoked.