Integration for Software Vendors

Note this is only required if you're developing "Third Party" software, used by many users of Access2View. If you're developing in-house software, contact us for a permanent Access Token. More details.

Authentication is handled using OAuth 2. Contact us and we'll supply you with a "Client ID" and "Client Secret". Use these tokens to complete the OAuth 2 "Authorization Code" dance. You'll receive a permanent Access Token to the API of the account you've connected.

Supply this Access Token on every request to the API as the Authorization header. For example if you're supplied the Access Token Bearer foobar728, supply the header: Authorization: Bearer foobar728.

Your language/framework likely has an OAuth 2 Client library available. If that's the case you can just configure that and not have to worry about much of this at all.

OAuth 2 Flow

Step 1. Redirect user to request integration

In your application you may have a "Connect with Access2View" button. This should redirect the user to the OAuth Authorization URL.

Field Description
response_type Must be code REQUIRED
client_id The Client ID you were provided REQUIRED
redirect_uri The URL in your app where the user will be sent back to after accepting/declining. This must match the URL you supplied us. REQUIRED
scope profile.read REQUIRED
state An optional random string you can use to protect against CSRF attacks - we'll send this parameter back in the next step for you to verify

For example you will redirect the user to a URL like so:

https://wms.access2view.co.uk/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URL
&scope=profile.read
&state=AN_OPTIONAL_NONCE

The user will now login to their Access2View account. We'll present them with a page confirming they want to give your application access to do certain actions on their behalf.

Step 2. We redirect back to your site

Assuming the user approves your request, we will redirect back to your site with a temporary code as the code URL parameter and the state you provided us.

Step 3. Exchange the code for an Access Token

Send the code parameter aquired from the redirect in the previous step back to us along with your application details to receive a permanent Access Token for the user.

Your request MAY specify a response format using the Accept header as application/json or application/xml. If you don't supply one, the response will be supplied as application/json.

Your Request

Send POST to https://wms.access2view.co.uk/oauth/authorize

Send the correct Content-Type header for the format of data you're sending. According to the OAuth 2 spec this should only be application/x-www-form-urlencoded. However for your convenience we also support application/json or application/xml.

Send the correct Accept header for the format of data you wish to receive. According to the OAuth 2 spec this should only be application/json. However for your convenience we also implement the draft alternate encoding spec, adding support sending responses as application/xml or application/x-www-form-urlencoded.

Field Description
grant_type Must be authorization_code REQUIRED
code The code parameter you just received REQUIRED
client_id The Client ID you were provided REQUIRED
client_secret The Client Secret you were provided REQUIRED
redirect_uri The URL in your app where the user was previously redirected to. This must match the field provided in the first request REQUIRED

If you send Content-Type: application/x-www-form-urlencoded (DEFAULT)

grant_type=authorization_code&
code=XXX&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=YOUR_REDIRECT_URI

If you send Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

If you send Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<json:object xmlns:json="http://www.ibm.com/xmlns/prod/2009/jsonx" xsi:schemaLocation="http://www.datapower.com/schemas/json jsonx.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <json:string name="grant_type">authorization_code</json:string>
  <json:string name="client_id">YOUR_CLIENT_ID</json:string>
  <json:string name="client_secret">YOUR_CLIENT_SECRET</json:string>
  <json:string name="redirect_uri">YOUR_REDIRECT_URI</json:string>
</json:object>

Our Response

Our Access Tokens do not expires unless explicitly revoked by the user or by Access2View.

Field Description
access_token The Access Token
token_type Will always be Bearer

If you sent Accept: application/json (DEFAULT)

{
  "access_token": "THE_ACCESS_TOKEN",
  "token_type": "Bearer"
}

If you sent Accept: application/xml

<oauth>
  <access_token>THE_ACCESS_TOKEN</access_token>
  <token_type>bearer</token_type>
</oauth>

If you sent Accept: application/x-www-form-urlencoded

access_token=THE_ACCESS_TOKEN&token_type=bearer