🔐Authorization

OAuth 2.0 is the industry standard protocol for authorisation. OAuth is an open-standard protocol that allows data sharing between parties with the consent of the user; without the user having to disclose passwords. Our APIs leverage OAuth protocols, using a standardised framework to ensure that using them is simple.

Click here for more information

Authorization Flow

We use OAuth2 JWT flows to secure interactions. Below are CURL, HTTP or C# HttpClient examples for typical CIPC API flows to request, return and use a token, which is required to process queries. The CIPC API is sessionless, so each "session" always begins with the OAuth2 JWT Access Token Flow.

Access Token Flow

This flow shows the steps required to interact with the API

1. Send an HTTP POST request to the tokenUrl: /oauth2/token

cURL

POST /oauth2/token HTTP/1.1 
Host: <example.com> 
Content-Type: application/x-www-form-urlencoded 
Body: {
  "grant_type": password,
  "client_id": "CIPC Client",
  "username": "username",
  "password": "password",
  "scope": "scope"
}

HTTP

POST /oauth20/token HTTP/1.1
Host: <example.com> 
Ocp-Apim-Subscription-Key: a11...f1ee
Content-Type: application/x-www-form-urlencoded
Content-Length: 189

grant_type=password&client_id={client_id}&username={username}&password={password}&scope={scope}

C# - HttpClient

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "<example.com>/oauth20/token");
request.Headers.Add("Ocp-Apim-Subscription-Key", "a11f1.....722ee");
var collection = new List<KeyValuePair<string, string>>();
collection.Add(new("grant_type", "password"));
collection.Add(new("client_id", "client_id"));
collection.Add(new("username", "username"));
collection.Add(new("password", "password"));
collection.Add(new("scope", "scope"));
var content = new FormUrlEncodedContent(collection);
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

1. Upon a successful authorization grant, the server will respond with an access_token

HTTP/1.1 200 OK
Request URL: <example.com>/oauth2/token
Date: <EEE, dd MMM yyyy HH:mm:ss z>
Content-Length: 500
Body: {
  "access_token": "eyJ...124nOvc",
  "token_type": "bearer",
  "expires_in" : 3600,
  "refresh_token": "eyJ...124nOvc"
}

1. Add a new Authorization header with type Bearer and the contents of the above access_token

POST </enterprise/information> HTTP/1.1
Host: <apim.cipc.co.za> 
Authorization: Bearer yJ...124nOvc
Content-Type: application/json; charset=utf-8 
Body: <...>

Once an access_token has been acquired, it can be used on all queries with an account until it returns a 401. If this occurs, simply request a new token using existing client_id, refresh_token and scopevalues, and set grant_type to refresh_token.