Authentication
Property Deck has two methods of authentication, OAuth 2.0 and personal access tokens.
Please request an OAuth client id and secret, or personal access token by emailing
info@propertydeck.co.uk
Usage
Both Personal Access Tokens and OAuth access tokens should be used as Bearer tokens. These may be sent in the Authorization header of your request
Authorization: Bearer <token>
Scopes
| Scope | Description |
|---|---|
profile.read | Access basic profile information |
profile.write | Update basic profile information |
properties.read | View properties |
properties.write | Create, update and delete properties |
contacts.read | View contacts |
contacts.write | Create, update and delete contacts |
statuses.read | View contact and property statuses |
statuses.write | Create, update and delete statuses |
types.read | View contact types |
types.write | Create, update and delete contact types |
attachments.read | View contact and property attachments |
attachments.write | Upload and delete attachments |
attachment-shares.read | View who an attachment has been shared with |
attachment-shares.write | Share attachments |
attachment-share-logs.read | View when an attachment has been viewed and downloaded |
notes.read | View contact and property notes |
notes.write | Create and delete notes |
competencies.read | View competencies |
competencies.write | Create, update and delete competencies |
users.read | View users that belong to the account |
users.write | Create, update and delete users |
custom-fields.read | View custom fields |
custom-fields.write | Create, update and delete custom fields |
reminders.read | View reminders |
reminders.write | Create, update and delete reminders |
Personal Access Tokens
// TODO: Explain personal access tokens and how to get one
OAuth
The Property Deck API adheres to the OAuth 2 specification.
Getting an Access Token
1. Redirect the user to request integration
In your application you may have a "Connect with Property Deck" button. This should redirect the user to the OAuth Authorization URL.
Parameters
| Field | Description |
|---|---|
response_type | Must be code |
client_id | The client ID of your Property Deck application |
redirect_uri | The URL in your app where the user will be sent back to. Must be in your application's approved URL list |
scope | A space-separated list of scopes you would like to request from the user |
state | An unguessable random string. It can be used to protect against cross-site request forgery attacks |
2. Property Deck redirects back to your site
Assuming the user approved your request for integration, we will redirect back to your site with a temporary code in the code parameter and the state your provided us. If the state does not match what you expect, abort the request.
3. Exchange the code for an Access Token
Send the code parameter acquired from the redirect in the previous step back to Property Deck along with your application details to receive a permanent Access Token for the user.
- Your request MUST be a
POSTrequest - Your request MUST be encoded as
x-www-form-urlencoded
Parameters
| Field | Description |
|---|---|
grant_type | Must be authorization_code |
code | The code parameter you just received |
client_id | The Client ID of your Property Deck application |
client_secret | The Client Secret of your Property Deck application |
redirect_uri | The URL in your app where the user was previously redirected to. Must be in your application's approved URL list |
Response
| Field | Description |
|---|---|
token_type | Will always be Bearer |
access_token | The access token you'll use to access the Property Deck API |
expires_in | The number of seconds until the access token expires |
refresh_token | The refresh token you'll use to get a new access_token when it expires |
Access Tokens and Refresh Tokens have a lifetime of 30 days and 6 months respectively. If your refresh token expires your user must re-approve your application by sending them through the OAuth flow again.
Refreshing an Access Token
When an Access Token expires you can exchange the refresh token for a new one, you'll also receive a new Refresh Token at the same time.
- Your request MUST be a
POSTrequest - Your request MUST be encoded as
x-www-form-urlencoded
Parameters
| Field | Description |
|---|---|
grant_type | Must be refresh_token |
refresh_token | The refresh token you received when retrieving an access token |
client_id | The Client ID of your Property Deck application |
client_secret | The Client Secret of your Property Deck application |
scope | A space-separated list of scopes you would like to access |
Response
| Field | Description |
|---|---|
access_token | Your new access token you'll use to access the Property Deck API |
refresh_token | Your new refresh token you'll use to retrieve another access token |
expires_in | The number of seconds until the access token expires |