This is a new service - your feedback (opens in a new tab) will help us to improve it.

  1. Home
  2. Tutorials

Tutorials


Before you start

All base URLs in these tutorials use the test environment.

All code snippets in these tutorials are in CSharp (C#). They use the RestSharp (opens in a new tab) library to access HTTP resources.

You can find more code samples in our public GitHub repositories. They're available in:

These tutorials use a simple DfE Information (example) API that exposes 3 endpoints. The paths are:

  • /dfe/open-info
  • /dfe/application-info (application authorises it using OAuth 2.0 access token)
  • /dfe/user-info (application authorises it using OAuth 2.0 authorisation grant flow)

All 3 use the GET method and give the message 'DfE Information'

Getting your subscription keys

You'll need an API subscription key header for all 3 endpoints. Before running any of the examples, follow these steps:

  • Create an account in the DfE Developer Hub.
  • Register your application that will integrate with the DfE APIs.
  • Copy your client ID and secret details.
  • Subscribe to the DfE Information API and choose the sandbox environment.
  • Make sure you have a primary and secondary subscription key.
  • Copy the primary key to use in the examples.

Accessing an open endpoint

In this example, you will access the DfE Information API open-info endpoint.

You do not need an access token for this endpoint because it does not need an authorisation header. You do need to send a subscription key

Issue a GET request to:

https://oat-api-customerengagement.platform.education.gov.uk/dfe/open-info
// construct the GET request for our DfE Information endpoint var client = new RestSharp.RestClient('https://dev-api-customerengagement.platform.education.gov.uk'); var request = new RestSharp.RestRequest('dfe/open-info', RestSharp.Method.GET); request.AddHeader('Ocp-Apim-Subscription-Key', '992519688c7c43ef916add082ac49e33'); // Add Subscription Key Header request.AddHeader("Ocp-Apim-Subscription-Key", "992519688c7c43ef916add082ac49e33"); // Execute the query and retreive results var queryResult = client.Execute(request); // extract the HTTP status HttpStatusCode statusCode = queryResult.StatusCode; int numericStatusCode = (int)statusCode;

Accessing an application-restricted endpoint

In this example, you will request an access token in your code (using your client ID and secret) and then use it to access the DfE Information API application-info endpoint.

See the authorisation section for information about requesting an access token.

1. Go to the DfE Information API documentation page and copy the OAuth token endpoint URL

2. Request an OAuth 2.0 access token in your application code:

private string refresh_token { get; set; } private string token { get; set; } // construct the request for access token var client = new RestClient("<Paste token endpoint here>"); var request = new RestRequest("dfe/application-info", Method.POST); request.AddHeader("content-type", "application/x-www-form-urlencoded"); request.AddParameter("grant_type", "client_credentials"); request.AddParameter("client_id", "<Paste-your-client-id-here>"); request.AddParameter("client_secret", "<Paste-your-client-secret-here>"); // make call to get token IRestResponse response = client.Execute(request); // Extract token token = JObject.Parse(response.Content).SelectToken("$..access_token").ToString(); refresh_token = JObject.Parse(response.Content).SelectToken("$..refresh_token").ToString();

3. Make a GET request to the DfE Information API application-info endpoint:

https://oat-api-customerengagement.platform.education.gov.uk/dfe/application-info
// prepare and make an api call to application authenticated endpoint var client = new RestClient("https://oat-api-customerengagement.platform.education.gov.uk"); var request = new RestRequest("dfe/application-info", Method.GET); request.AddHeader("authorisation", "Bearer " + token); request.AddHeader("ocp-apim-subscription-key", "992519688c7c43ef916add082ac49e33"); request.AddHeader("accept", "application/json; charset=utf-8"); response = client.Execute(request);

This should give you a DfE department high level information response.

Accessing a user-restricted endpoint

In this example, you will request an OAuth 2.0 access token in your code (using your client ID and secret) and use it to access the DfE Information API user-info endpoint.

The user-restricted endpoints give details about their authorisation endpoint on the API page.

Authorise user

To begin the flow, you'll need to get the user's authorisation. This may include one or both of:

  • authenticating the user
  • obtaining user consent for the requested permission level (if you do not have it)

To authorise the user, your app must send the user to the authorisation URL provided on the user-restricted API page. The scope details would also be provided on the specific API page.

1. Request an OAuth 2.0 authorisation code with the required scope:

https://user-restricted-end-point -login/authorise?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://YOUR_APP/callback&scope=SCOPE&audience=API_AUDIENCE&state=STATE

As an example, your HTML snippet for your authorisation URL when adding login to your app might look like:

<a href="https://user-restricted-end-point-login/authorise?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://YOUR_APP/callback&scope=SCOPE&audience=API_AUDIENCE&state=xyzABC123">Sign In</a>

The user will be redirected to the DfE Identity login screen. When they've entered their credentials, they'll be asked to authorise the application to access the requested scope.

When the user has given the requested authority, we will return to the application via the redirect URL. We'll provide an authorisation code as a query string parameter.

This authorisation code can then be exchanged for an OAuth 2.0 access_token and a refresh_token.

2. Exchange the OAuth 2.0 authorisation code for an access token

// make a call to token endpoint to get access token var client = new RestClient('<Paste OAuth Token URL Here>'); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/x-www-form-urlencoded"); request.AddParameter("grant_type", "authorisation_code"); request.AddParameter("code", "<Paste-authorisation-code-here>"); request.AddParameter("client_id", "<Paste-your-client-id-here>"); request.AddParameter("client_secret", "<Paste-your-client-secret-here>"); request.AddParameter("redirect_url", "<Paste-your-redirect-url-here>"); IRestResponse response = client.Execute(request); // Extract token token = JObject.Parse(response.Content).SelectToken("$..access_token").ToString(); refresh_token = JObject.Parse(response.Content).SelectToken("$..refresh_token").ToString();

3. Make a GET request to the ‘DfE Information’ API user-info endpoint:

https://oat-api-customerengagement.platform.education.gov.uk/dfe/user-info
// prepare and make an API call to application authenticated endpoint var client = new RestClient("https://oat-api-customerengagement.platform.education.gov.uk"); var request = new RestRequest("dfe/user-info", Method.GET); request.AddHeader("authorisation", "Bearer " + token); request.AddHeader("ocp-apim-subscription-key", "992519688c7c43ef916add082ac49e33"); request.AddHeader("accept", "application/json; charset=utf-8"); response = client.Execute(request);

4. Refresh an expired OAuth 2.0 access_token:

This exchanges a refresh_token for a new access_token (and a new refresh_token).

// construct the GET request for refresh token var client = new RestClient("<Paste token endpoint here>"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/x-www-form-urlencoded"); request.AddParameter("grant_type", "refresh_token"); request.AddParameter("refresh_token", "<Paste refresh token here>"); request.AddParameter("client_id", "<Paste your client id here>"); request.AddParameter("client_secret", "<Paste your client secret here>"); // make a call to get refresh token IRestResponse response = client.Execute(request); // Extract token token = JObject.Parse(response.Content).SelectToken("$..access_token").ToString();