Authentication - Tech Documentation

Suggest Edits

An application programming interface (API) is a computing interface which defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.

The API's we provide allow you to programmatically activate products directly within your internal CRM.

This article includes:

  • [Prerequisites] (#prerequisites)
  • [Authentication] (#authentication)
  • [Questions] (#questions)

Prerequisites

This article assumes you have a general knowledge of command line interfaces and software development.

Authentication

The first step of working with our API's is to set up authentication for your client using OAuth 2.0 with the machine-to-machine flow.

The public GPG key is used to return your encrypted client_secret which can be decrypted using your private GPG key. You will also receive a client_id in plain text.

How to generate a GPG key pair

📘

Note

These instructions are based on GnuPG 2.2.26. If you use an older/newer version it can have slightly different parameters. Please refer to the documentation of the tool to find out how to generate your GPG key pair.

To generate your GPG key pair:

  1. Download and install the [GPG command-line tools] (https://www.gnupg.org/download/)
  2. Open terminal
  3. Run command: gpg --full-generate-key
  4. Accept default key kind: RSA and DSA
  5. Enter the key size 4096 is good enough
  6. You can specify how long the key will be valid, or press enter to accept default value (the key doesn't expire)
  7. Verify the data you have provided
  8. Enter your user ID information
  9. Enter your secure passphrase

📘

Note

Have questions? Email our Member Services team: [[email protected]] (mailto:[email protected]).

How to decrypt your client_secret provided by us

In the message from us, you will find your client_id (it's not encrypted) and your client_secret (it's encrypted). the encrypted message starts with -----BEGIN PGP MESSAGE----- and ends with -----END PGP MESSAGE----- .

  1. Create a file and put the encrypted message in this file
  2. Run the command:
    gpg --decrypt filename-with-encrypted-message > unencrypted.txt
  3. You will be asked to provide your passphrase
  4. Now in the file unencrypted.txt , you will find your client_secret . Check it with the command cat unencrypted.txt

❗️

Warning

Do not forget your passphrase. You will not be able to decrypt a message if you don't know the passphrase

How to export your public key

You need to export your public key so you can share it with us. To do that:

  1. In the terminal, run the below command, and not your key identifier
    gpg --list-secret-keys --keyid-format LONG

For example, for such output:

 gpg --list-secret-keys --keyid-format LONG
 /Users/hubot/.gnupg/secring.gpg
 ------------------------------------
 sec   rsa4096/A6FC40C322107B47 2020-07-20 [SC]
       B6FB15B6B746A9B9E319E868A6FC40C322107B47
 uid                 [ultimate] John Smith <[email protected]>
 ssb   rsa4096/0290636A51F3EB7A 2020-07-20 [E]

Your keyId will be A6FC40322107B47

  1. Run the command:

gpg --armor --export A6FC40C322107B47

  1. Copy your GPG public key which starts with -----BEGIN PGP PUBLIK KEY BLOCK----- and ends with -----END PGP PUBLIC KEY BLOCK----- and provide it to your technical contact

❗️

Warning

Keep your client_id and client_secret secure. This pair allows access to our API on your behalf. If you think that this could be compromised, please contact your technical contact immediately to revoke access to your client_id and generate your new pair.

How to authenticate your client

Use your client_id and client_secret to authenticate your client and make requests to our API, as per the examples below:

Examples to authenticate:

POST https://services-auth.services.zoopla.co.uk/oauth2/token

Headers:

  • content-type : application/x-www-form-urlencoded
  • Authorization : Basic token

Payload:
--data-urlencode 'grant_type=client_credentials'
--data-urlencode 'scope=api/api_access'

📘

Note

token is the Base64 encoded your client_id and client_secret . You can find this value with: echo -n 'client_id:client_secret' | openssl base64

Error codes

You'll get a HTTP 401 or 403 if your token is invalid or expired.

Example cURL request to authenticate: 

 curl --location --request POST 'https://services-auth.services.zoopla.co.uk/oauth2/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \ 
 --header 'Authorization: Basic MzRvYmFyZWxjZDdwbmpycWZmMDY2anVpY3Y6ODBhOXFxaW02bDhzdW5rbWg2azNyaXNobGZpbXF1ZjJrNnNhODFtazVuMmxlM29pdGM0' \ 
 --data-urlencode 'grant_type=client_credentials' \ 
 --data.urlencode 'scope=api/api_access'

If your request is valid, you will find the access_token in the response. This token is required to make further requests to the API.

Example response: 

{
  "access_token": "eyJraWQiOiJMU0VyUkowYk5ubkg0UGorUUZObXdnd08wNk1UdXBoNVJJOERlRGp3ZXg4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIzNG9iYXJlbGNkN3BuanJxZmYwNjZqdWljdiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXBpXC9hcGlfYWNjZXNzIiwiYXV0aF90aW1lIjoxNTk1MjM3NzAzLCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0xLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtMV9nMHFlWlJuYlQiLCJleHAiOjE1OTUyNDEzMDMsImlhdCI6MTU5NTIzNzcwMywidmVyc2lvbiI6MiwianRpIjoiMDQ1M2UwZjctN2M2NS00OWEzLTkyZDQtZjBiODNkYmIwYjRiIiwiY2xpZW50X2lkIjoiMzRvYmFyZWxjZDdwbmpycWZmMDY2anVpY3YifQ.Mp4Bd9_BzFrN2-mxLIUqgLPvh1zizW5ovc_bBxsMdZ21DsKWtjDtzR4wYwYiLZp6wJmp4QgENSd6cOoakJtQD4tyGeLeeq8t8HelqFk9MzN68UnhAqxJKcLdxwVExFU4D3AGsP3i6V2hHnwjgaEQ-qukJpBIQub_BUG5X-_4bwWar1vM0sAogElcmqY_wGg11Jqz0EWCOQbsQsiD491xBhWMjor635MDIF52Wnp1qHgOVfZVuDnVnQgSdN08Yboi-30TqFezo4CZxTnCfA2ltiHNHTuXDPtdQ2Z1SFUNIaGfHgHNNT0VbpiLTwcRzTKV_buv88DMvgwo-lX4oc9k1g",
  "expires_in": 3600,
  "token_type": "Bearer"
}

📘

Note

When you get the access_token you can make requests to our API. You need to provide this access_token in Authorization header like this:
Authorizartion: Bearer {access_token}

Questions

If you have any questions related to this technical document / API, please contact [[email protected]] (mailto:[email protected]).

Updated 8 months ago