PieSync

We have a sample project using the APIs below: https://github.com/RealGeeks/piesync-sample. If you’re a PieSync developer request access to this repo in Real Geeks.

Authentication

PieSync 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 /piesync/oauth/authorize/

PieSync redirect users to this authorization URL with the following arguments in the query string:

  • client_id: PieSync 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 PieSync to maintain state between this request and the redirect uri, Real Geeks will include this value when redirecting the user-agent back to PieSync

When the user authenticates Real Geeks will redirect the user-agent back to PieSync 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 PieSync. this value matches the one provided

In case any errors happen during the authentication Real Geeks will redirect the user back to PieSync 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 PieSync uses the code to exchange for an access token

POST /piesync/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 repectively

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 PieSync 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 PieSync. A user in Real Geeks can own multiple sites.

PieSync can manage the subscription in Real Geeks. When a subscription exists that means PieSync 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

PUT /piesync/subscription/{site-uuid}/

Create a new subscription or override the existing one. Only one subscription is allowed per site.

Request body should be a JSON with format:

{
  "url": "http://api.piesync.com/v1/realgeeks",
  "secret": "s3cret"
}

url is the endpoint that will receive requests from Real Geeks. The types of requests sent will be only created and updated, see our docs on Requests Types for details and format

secret is a string that will be used to sign all requests and should be used by PieSync to verify if the request originated from Real Geeks. More details on our docs on Security

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

422: Validation failed in at least one of the fields provided. The error body will also contain a fields key with more details. Example:

{
  "error": "Invalid fields",
  "fields": {"url": ["This field cannot be blank."]}
}

500: Unknown server error

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

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

{
  "url": "http://api.piesync.com/v1/realgeeks",
  "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 , PUT will also fix because it will remove all existing ones and create a new one

DELETE /piesync/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