Open Menu

© 2018 Capita Business Services Ltd. All rights reserved.

Capita Education Software Solutions is a trading name of Capita Business Services Ltd. Our Registered office is 30 Berners Street, London, W1T 3LR and our registered number is 02299747. Further information about Capita plc can be found in our legal statement.

Web - Building Apps for mixed API Sets

It can be a little confusing when a TI takes a the full set of our APIs and then joins them up to create a solution.

Access Tokens

There can be up to 3 access tokens required.

  1. Vendor management token (Client id contains vms_) 
  2. DeX Token (Client id contains simsprimary_)
  3. One Roster / RAP (Client ID contains oneroster_0

1. The vendor management token allows access to the specific RAP API calls for vendor management and enables the TI to find out:

  1. Who their customers are for a specified application
  2. The client credentials for their customers for a specified application

It does not enable access of itself to any school data.

Header Data Value
grant_type client_credentials
client_id {{client_id}} (vmc-)
client_secret {{client_secret}} 
scope partner-read partner-write
acr_values orgselected:{{organisation_id}} (Optional)

acr_values are not needed because the application id is specified in the URL but it won't hurt to include it.

2. The DeX Token.  Data from the Vendor Management calls above can be used to get the DeX client ID and Secret. These are used to create a token request which will allow access to data via our DeX Odata calls.  This token cannot be used to get Vendor Management or One Roster / RAP calls (see below).  When requesting a 'DeX' access token, a valid organisation ID must be specified in the header

Header Data Value
grant_type client_credentials
client_id {{client_id}} (sas-simsprimary-)
client_secret {{client_secret}} 
scope partnerserverapplication
acr_values orgselected:{{organisation_id}} (Required)

 

Oddly (or so it may seem), this will likely get a token even if an invalid or no organisation is passed in because the client id and secret are valid.  If 500 errors are returned when the use of the token is attempted, harvest the token and check it out in jwt.io if the token is missing a line containing 'userorganisationidentifier' then this suggests an issue with the org id.

     "userorganisationidentifier": "|cccccc9-ccc1-ccccf-cccc-CCCCCC14|S",

 

3. One Roster / RAP Tokens

A DeX token  can't access One Roster / RAP for school data and vice versa.  Typically a 500 error is returned when you try.  The reason for this is that you have a valid token but not for the call that you are trying to make.  Arguably this should return a 4xx error but this should only occur during development.

Acr values are optional and will work even if the value provided is wrong.

Header Data Value
grant_type client_credentials
client_id {{client_id}} (sas-oneroster-)
client_secret {{client_secret}} 
scope onerosterapi organisation partner rapapi
acr_values

orgselected:{{organisation_id}} (Optional)

 

API Calls

Assuming that the correct token is provided then only DeX OData calls currently need an API Manager Key (OCP_Apim_Subscription_Key).

Header Data Value
Authorization Bearer {{token}}
Ocp-Apim-Subscription-Key {{{subscription_key}}

There is no harm in passing the API Manager key when requesting a token or One/Roster/RAP but failure to pass it when requesting DeX Odata will return an error.