Developers
Get access

Authentication

The API uses OAuth 2.0 client credentials. Exchange your client ID and secret for an access token, cache it until it expires, and send it as a bearer token. One token works for every product, now and as we add more.

Get a token

Send your client ID and secret to the token URL, https://auth.checkmystreet.co.uk/oauth2/token:

curl -X POST https://auth.checkmystreet.co.uk/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id="$CMS_CLIENT_ID" \
  -d client_secret="$CMS_CLIENT_SECRET"
const tokenRes = await fetch("https://auth.checkmystreet.co.uk/oauth2/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.CMS_CLIENT_ID,
    client_secret: process.env.CMS_CLIENT_SECRET,
  }),
});
const { access_token, expires_in } = await tokenRes.json();
import os
import requests

token_res = requests.post(
    "https://auth.checkmystreet.co.uk/oauth2/token",
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["CMS_CLIENT_ID"],
        "client_secret": os.environ["CMS_CLIENT_SECRET"],
    },
    timeout=10,
)
token_res.raise_for_status()
access_token = token_res.json()["access_token"]
using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient();

var tokenRes = await http.PostAsync(
    "https://auth.checkmystreet.co.uk/oauth2/token",
    new FormUrlEncodedContent(new Dictionary<string, string>
    {
        ["grant_type"] = "client_credentials",
        ["client_id"] = Environment.GetEnvironmentVariable("CMS_CLIENT_ID")!,
        ["client_secret"] = Environment.GetEnvironmentVariable("CMS_CLIENT_SECRET")!,
    }));
tokenRes.EnsureSuccessStatusCode();

var tokenJson = await tokenRes.Content.ReadFromJsonAsync<JsonElement>();
var accessToken = tokenJson.GetProperty("access_token").GetString();

The samples read your credentials from the environment variables CMS_CLIENT_ID and CMS_CLIENT_SECRET. To try them with the sandbox credential, use the values in the Quickstart.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Cache it until it expires

Tokens last 30 minutes: expires_in is 1800 seconds. Keep one token and reuse it for every call until shortly before it expires, rather than requesting a new token each time.

let cached = null;

export async function getToken() {
  if (cached && Date.now() < cached.expiresAt) return cached.token;
  const res = await fetch("https://auth.checkmystreet.co.uk/oauth2/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.CMS_CLIENT_ID,
      client_secret: process.env.CMS_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`Token request failed: ${res.status}`);
  const body = await res.json();
  // Refresh a minute early so a token never expires mid-request
  cached = { token: body.access_token, expiresAt: Date.now() + (body.expires_in - 60) * 1000 };
  return cached.token;
}
import os
import time
import requests

_cached = {"token": None, "expires_at": 0.0}

def get_token():
    if _cached["token"] and time.time() < _cached["expires_at"]:
        return _cached["token"]
    res = requests.post(
        "https://auth.checkmystreet.co.uk/oauth2/token",
        data={
            "grant_type": "client_credentials",
            "client_id": os.environ["CMS_CLIENT_ID"],
            "client_secret": os.environ["CMS_CLIENT_SECRET"],
        },
        timeout=10,
    )
    res.raise_for_status()
    body = res.json()
    # Refresh a minute early so a token never expires mid-request
    _cached["token"] = body["access_token"]
    _cached["expires_at"] = time.time() + body["expires_in"] - 60
    return _cached["token"]

Send it as a bearer token

Put the token in the Authorization header of every call:

POST /partners/v1/valuations HTTP/1.1
Host: api.checkmystreet.co.uk
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

A missing, invalid or expired token gets 401, with an OAuth error body such as {"error": "invalid_token"}. Get a new token, then retry the call once.

Keep secrets safe

To change a secret without downtime, use the console: create a second login, switch your servers to it, then revoke the old one.

Updated