NAV
cURL C# JavaScript Python

Authentication

Authentication Flow

Applications can use the authorization code grant type of the OAuth2 specification to obtain an access token by redirecting a user to the authorization endpoint of the CINC site. A user can then authorize your application with the allowed scopes. Obtained access tokens will give the application access to specific actions based on the scopes selected.

You obtain a user's consent to make API calls on their behalf by redirecting their user-agent (browser, webview, etc) to the authorization endpoint with the parameters listed below.

Example request: Obtain user's consent

curl -X GET -G "https://authv2.cincapi.com/integrator/authorize" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=myclientid" \
  -d "response_type=code" \
  --data-urlencode "redirect_uri=https://myapp.com/callback" \
  --data-urlencode "scope=api:read" \
  -d "state=12345"

// In production code, don't destroy the HttpClient through using, but better use IHttpClientFactory factory or at least reuse an existing HttpClient instance
// https://docs.microsoft.com/en-us/aspnet/core/fundamentals/http-requests
// https://www.aspnetmonsters.com/2016/08/2016-08-27-httpclientwrong/
using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("GET"), "https://authv2.cincapi.com/integrator/authorize?client_id=myclientid&response_type=code&redirect_uri=https://myapp.com/callback&scope=api:read&state=12345"))
    {
        var response = await httpClient.SendAsync(request);
    }
}

fetch('https://authv2.cincapi.com/integrator/authorize?client_id=myclientid&response_type=code&state=12345', {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'redirect_uri=https://myapp.com/callback&scope=api:read'
})
  .then(response => response.json())
  .then(data => console.log(data));

import requests

headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
}

params = {
    'client_id': 'myclientid',
    'response_type': 'code',
    'state': '12345',
}

data = 'redirect_uri=https://myapp.com/callback&scope=api:read'

response = requests.get('https://authv2.cincapi.com/integrator/authorize', params=params, headers=headers, data=data)

Example response

{
  "request": {
    "responseURL": "https://myapp.com/callback?code=abcdefghijkl&scope=api:read&state=12345",
    // ... 
  },
  // ...
}

Parameters

Name Type Description
client_id String Required Unique client identifier obtained through the application registration process.
response_type String Set to code to request that an authorization code be sent back to the application return URL.
redirect_uri String Application callback URL where the authorization code is sent. This must match the URL registered for your application.
scope String Space-delimited string of the scopes you would like.
state String An opaque value used to maintain state between the authorize request and the callback.

2. Process the authorize callback

Once the user authorizes your application, CINC redirects (HTTP 302) the user-agent to the return URL with the authorization code appended in the code query parameter.

3. Obtain an access token

The authorization code received above can then be exchanged for an access token.

Example request: Obtain an access token

curl -X POST "https://authv2.cincapi.com/integrator/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=myclientid" \
  -d "client_secret=myclientsecret" \
  -d "grant_type=authorization_code" \
  -d "code=abcdefghijkl" \
  --data-urlencode "redirect_uri=https://myapp.com/callback" \
  --data-urlencode "scope=api:read"

// In production code, don't destroy the HttpClient through using, but better use IHttpClientFactory factory or at least reuse an existing HttpClient instance
// https://docs.microsoft.com/en-us/aspnet/core/fundamentals/http-requests
// https://www.aspnetmonsters.com/2016/08/2016-08-27-httpclientwrong/
using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://authv2.cincapi.com/integrator/token"))
    {
        var contentList = new List<string>();
        contentList.Add("client_id=myclientid");
        contentList.Add("client_secret=myclientsecret");
        contentList.Add("grant_type=authorization_code");
        contentList.Add("code=abcdefghijkl");
        contentList.Add($"redirect_uri={Uri.EscapeDataString("https://myapp.com/callback")}");
        contentList.Add($"scope={Uri.EscapeDataString("api:read")}");
        request.Content = new StringContent(string.Join("&", contentList));
        request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/x-www-form-urlencoded"); 

        var response = await httpClient.SendAsync(request);
    }
}

fetch('https://authv2.cincapi.com/integrator/token', {
    method: 'POST',
    body: new URLSearchParams({
        'client_id': 'myclientid',
        'client_secret': 'myclientsecret',
        'grant_type': 'authorization_code',
        'code': 'abcdefghijkl'
    })
})
  .then(response => response.json())
  .then(data => console.log(data));

import requests

data = {
    'client_id': 'myclientid',
    'client_secret': 'myclientsecret',
    'grant_type': 'authorization_code',
    'code': 'abcdefghijkl',
}

response = requests.post('https://authv2.cincapi.com/integrator/token', data=data)

Example response

{
  "access_token": "8jhsJD03mds92HDs9sl3Ld",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "s982jXDpk20kasd0DK293ks",
  "scope": "api:read"
}

Headers

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

Parameters

Name Type Description
grant_type String Required Value should be authorization_code.
code String The authorization code that was sent to your application's return URL.
redirect_uri String Application callback URL where the authorization code is sent. This must match the URL registered for your application.
scope String Space-delimited string of the scopes you would like.

All Scopes

api:create

Allows create access at the site level on behalf of the user. The creation of a new object (i.e. lead) is limited to just agents with broker level status.

api:delete

Allows for deleting or removing at the site level on behalf of the user. The current version only supports providing access for agents with broker level status.

api:event

Allows for registering and receiving events at the site level on behalf of the user. Events can be read with the api:read scope and will be properly restricted by permissions. However, receiving asynchronous events is for agents with broker level status only.

api:read

Allows read access to the information at the site level on behalf of the user. The data is restricted per the permissions of the user that provided access. The current version only supports providing access for agents with broker level status.

api:update

Allows for updating information at the site level on behalf of the user. The current version only supports providing access for agents with broker level status.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

cURL C# JavaScript Python