How to Build an OAuth Integration with the Assembly Platform

Please don’t hesitate to get in touch if you have questions. You can email us at or give us a call at 020 8506 6100.

What is OAuth?

OAuth is an open standard designed to allow a 'resource owner' (in our case a school) grant limited access to data which is held on an resource server (the Assembly Platform) to a third party (you, the app developer). Data access is usually scoped to particular items or sets of data.

Why does Assembly use OAuth?

At Assembly we strongly believe in data security and a school's right to choose (opt-in rather than be forced to opt-out) which data a third party application may access. We believe that schools should be able to revoke access to the data held on the Assembly Platform at any time and we feel that OAuth provides an excellent mechanism to facilitate this process and help schools own their data properly.

Whats the basic flow to authorise my app?

Here's what needs to happen in order for a school to authorise your app to access their data:

  • A school user can initiate the authorisation request from the Assembly Platform but you can also provide a page on your app to initiate the process.
  • From the Platform a user would hit the 'Authorise Now' button for your app. All this button does is send the user to the Install URI that you provide when you configure your app on the Platform.
  • At this point your app can either:
    • Allow the user to sign in to your app so that you know who they are (or do any other initial setup that you want) and then provide a link to being the authorisation process OR
    • Re-direct the user straight back to to start the OAuth process.
  • Once the user accepts the authorisation request the Platform will use the Redirect URI you provided to callback to your app with a temporary code.
  • Your app must use the temporary code from the step above to request an access token and a refresh token which it must then store in a secure location.
  • Your app can now use the access token to make requests for the school's data.

How can I test my application's OAuth flow on Assembly Sandbox?

We provide a  sandbox environment which is completely separate from our production environment.

Because OAuth is a protocol that requires interaction from both the user and the application it can be difficult to test the flow fully. For this reason, on our sandbox environment, you are able to act as both the developer and as the school user in order to fully test your application's OAuth flow. 

Initial Configuration

Once you have signed up to sandbox, you will need to create a New Sandbox App:

Give the app a name and fill out any other information you desire (this is more important when you promote your application to production).

You should also provide links to a privacy policy so that when your app is live schools are able to easily see what your app will do with their data, what you will store and why.

In order to test the OAuth flow you must add a Redirect URI that points to where your application is being served from. It should be a special URI that the Assembly Platform will call back to when a user accepts your app's data request. 

The install URI will link to where the user kicks off the authorisation process - this will be where the Authorise Now button links to for your test school. 

In our  simplified Sinatra OAuth example, this takes the user to a button on the third party site that then initiates the Authorisation request to the Platform:

Of course, users could access this page directly from your site (without being directed there from the Assembly Platform). You may also want the user to sign in or sign up on your site before they reach this button. 

These URIs  can be an address on your local machine whilst you are building your application (as in the above screenshots) because the OAuth flow takes place in the browser.

Ensure that the List this App for other schools to find? check box is selected and click Create App to finish the process.

IMPORTANT: When you click the Create App button you'll be given a client_id and client_secret. You must make a note of these now. This is the only time you will be able to see this information.

Implementing the OAuth flow

The OAuth flow that your application must complete in order to get an access_token and refresh_token for each school is a multi-step process that takes place both on your app server and in the browser:

Step 1
In order to sign up to your application a user either clicks the Authorise Now button from the Assembly Platform or comes directly to your site. 
Step 2
A user clicks a link on your page and is redirected to the Assembly Platform. They must sign in to the Assembly Platform (if not already) and accept your app's request to be authorised to access their data. When you redirect the user's browser you must include the following URI parameters:
  • client_id : The ID you received when you registered your application with Platform sandbox or production
  • redirect_uri : The URI the the Platform will callback to when the user accepts or rejects the app authorisation request.
  • state : You should provide a unique code here generated by your app for each request. You'll use this code later to guard against CSRF.
  • scope : A list of scopes to which your application needs access. The available scopes are defined here.
Step 3

When you created your app you provided a  Redirect URI. The Assembly Platform will callback to this URI. The Platform will also check the URI you provided in your app configuration against the redirect_uri parameter in Step 2, above so they must be identical.

The callback is an HTTP GET and will include the following URI parameters:
  • code : A temporary authorisation code. You will exchange this for an access token in the next step.
  • state : The anti CSRF token that you provided above. You should check to see they are the same.
Step 4
You can now exchange the temporary code received in step 3 for an access token and a refresh token. You do so with a POST request to the Platform with the following URI parameters:
  • code : The temporary code from step 3.
  • redirect_uri : You must still provide the original redirect_uri at this stage otherwise the request will be rejected.
You must also provide your  client_id and  client_secret that you received when you registered your application with Platform sandbox or production. They must be sent in a Basic Authorization header and must be Base64 encoded.
For an example of the response body from the Platform please see the response in  this section of the API docs.
Step 5 (optional)
The final step in the OAuth flow is to use the access_token you received in Step 4 to get some basic information about the school who have authorised your app. 
A HTTP GET call to (or on the live environment) with the access_token as an Authorization header will return a school's name and URN. You can read more about that here

What next?

Once you're happy that your OAuth integration is working, you're ready to move across to the live environment and start onboarding schools. Please contact for more information on how to proceed. 

The process of configuring your app is largely the same as on the sandbox, but you should take more care to add proper descriptions, privacy policy links and so on.

Resources and Examples