Versions Compared

Version Old Version 1 New Version 2
Changes made by

Kurt Wagner (Unlicensed)

Kurt Wagner (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This document describes how to use OAuth 2.0 when accessing AffinityLive's API from an installed application

Contents

...

Table of Contents

Forming the URL

Handling the response

Accessing the resource

minLevel2

Overview

A user will be directed to visit an AffinityLive OAuth 2.0 URL with a set of query parameters. After authentication (handled by AffinityLive) the user will be presented with a PIN and a QRCode. The user will be prompted to supply the PIN to the installed application.

...

ParameterValuesDescription
client_idThe applications client id obtained from the API Control Panel.Indicates what API application is making the request. It is a unique string allocated to your application, which can be used across multiple deployments. For example: 34ad67fa2f@hq.local.affinitylive.com
response_typecodeThis value must be code for installed applications.
scopeThe permissions your application requests.A scope is used to convey what permissions your application requires when requesting permission from the end-user. Current available scopes are:
  • read(all) - Read only access to all data the user owns or has access to including personal information, and
  • write(all) - Read and write access to all data the user owns or has access to including personal information.
  • read({resource}) - Read only access to data related to the {resource} object.
  • write({resource}) - Read and write access to data related to the {resource} object.

Scope resources can be any of our endpoints. For example, companies, contacts or issues. The scope can be concatenated and delimited by a comma. For example:

  • read(all),write(companies,contacts) - read all information and write to only companies and contacts.
  • write(contacts,issues) - Read and write access to contact and issue data.

Example URL.

 

1
2
3
4
5
6

 

Code Block
https://hq.local.affinitylive.com/oauth2/v0/authorize?

scope=read(all)&

 

redirect_uri=https://app.com/oauth_callback&

response_type=code&

client_id=34ad67fa2f@hq.local.affinitylive.com

 


 

Please note that the above sample url should be encoded. For example purposes it was left in plain text.

...

Here is what a request may look like, where the client id and secret are encoded using base-64.

 

1
2
3
4
5
6
7
8
POST
Code Block
POST /oauth2/v0/token HTTP/1.1

Host: hq.local.affinitylive.com

Content-Type: application/x-www-form-urlencoded

Authorization: Basic {client_id}:{client_secret}

 

code=frLA0s1m_D&

 

grant_type=authorization_code

 

Upon a successful request, the response contains the following fields:

...

Sample accessing a company resource using access token in query:

 

 

1
Code Block
GET https://hq.local.affinitylive.com/public_api/v0/companies/1?_bearer_token=frLA0s1m_D

...

Sample using the prefered Authorization header method:

 

1
2
3
Code Block
GET /public_api/v0/companies/1 HTTP/1.1

Host: hq.local.affinitylive.com

Authorization: Bearer frLA0s1m_D

 

References and additional reading