CINC

Authentication

CINC will redirect users to Real Geeks OAuth server to login and obtain an access_token and site_uuid in the end of the process.

GET /cinc/oauth/authorize/

CINC will send users to this authorization URL with the following arguments in the query string:

  • client_id: CINC client_id provided by Real Geeks
  •  response_type: Must have value code
  •  redirect_uri: URL Real Geeks will redirect user back to after login. Must be registered with Real Geeks
  • scope: Use the following value: leadrouter:connect leadrouter:send
  • state: An opaque value used by CINC to maintain state between this request and the redirect uri, Real Geeks will include this value when redirecting the user-agent back to CINC

When the user authenticates Real Geeks will redirect the user-agent back to CINC redirect_uri including the following arguments in the query string:

  • code: Authorization code to be used in the token endpoint below
  • state: Same value provided by CINC. this value matches the one provided

In case any errors happen during the authentication Real Geeks will redirect the user back to CINC redirect_uri with an error argument in the query string. See the possible errors in the OAuth spec

This completes the first stage of OAuth, now CINC uses the code to exchange for an access token

POST /cinc/oauth/token/

The access token request is a POST using ​application/x-www-form-urlencoded format with the following fields:

  • grant_type: must have value authorization_code`
  • code: authorization code provided by the authorization url above
  • redirect_uri: same redirect_uri registered in Real Geeks

This request must be authenticated using HTTP Basic Auth with the client_id and client_secret provided by Real Geeks as username and password respectively

A successful response will contain a JSON body similar to:

{
   "access_token": "123",
   "refresh_token": "321",
   "token_type": "Bearer",
   "site_uuid": "aa808177-d2cc-415d-b504-a36abf39ac00",
   "site_domain": "www.site.com"
}
  • access_token: should be used to make requests to Real Geeks APIs
  • refresh_token: should be used to obtain a new access token when the current one expires
  • site_uuid: identifies the Real Geeks Site owned by this user that CINC is connected to, all requests to Real Geeks APIs will require a site_uuid in the URL
  • site_domain: can be used for display in the UI

Subscription

A subscription is a link between a Real Geeks site and CINC. A user in Real Geeks can own multiple sites.

CINC can manage the subscription in Real Geeks. When a subscription exists that means CINC will receive requests from Real Geeks when leads are created or updated.

All requests must include the access token in the Authorization header:

Authorization: Bearer <token>

Missing or invalid access token will return status code 401

Response body will be the subscription details, same as GET and status code 200

Error Response

The error response will be a JSON with format:

{"error": "Invalid JSON body"}

Possible status:

400: JSON body is invalid and could not be parsed

GET /cinc/subscription/{site-uuid}/

Return a JSON body with the subscription details of this site and status code 200

{
  "secret": "s3cret"
}

Error Response

The error response will be a JSON with format:

{"error": "Subscription not found"}

Possible status:

404: There is no subscription for this site, or the site does not exist. The error message will contain details

409: Multiple subscriptions found for this site, this is an invalid state and should not happen, clients are encouraged to use DELETE

DELETE /cinc/subscription/{site-uuid}/

Delete the existing subscription, does nothing if subscription does not exist

Error Response

The error response will be a JSON with format:

{"error": "Site not found"}

Possible status:

404: Site not found