OAuth

The OAuth endpoints are available to gain authorization to access a school's data. Click here to see an example of how to get started with implementing OAuth for the Assembly Platform.

OAuth calls should be made to: https://platform.assembly.education

OR: https://platform-sandbox.assembly.education

The only exception is the user info end-point, which are not part of the browser OAuth flow and therefore should be made to the api endpoint. e.g: https://api.assembly.education/me

Authorization Request

This endpoint is designed to be called from an end user's browser. Users should be redirected to this URL to request their authorization to use your app. Once completed the user will be redirected back to your apps redirect_uri.

Request

GET /oauth/authorize
Parameter Default Example Description
client_id 123

the client id of the app requesting access

redirect_uri https://example.com/callback

this value must exactly match your configured redirect URI

scope school students+contacts:optional

a '+' separated list of scopes to request access for. Scopes can be defined as optional by including :optional after the scope name

state nrboh24tfopnvd24

an opaque string that will be passed back to you in order to mitigate CSRF attacks

URI Template: /oauth/authorize{?client_id,redirect_uri,scope,state}

Response 302

Headers
Content-Type: text/html

Client Credentials Exchange

Allows the calling Application to exchange client credentials for an App level token. The functionality of App level tokens is currently limited to finding a list of schools who have authorized your App but, in future, you'll be able to use your App tokens for additional features.

Clients must provide their client_id and client_secret credentials via an HTTP Basic Authentication header.

App level tokens don't currently expire but this behaviour likely to change in the future so we recommend periodically refreshing tokens where possible.

Request

POST /oauth/token?grant_type=client_credentials
Headers
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Parameter Default Example Description
grant_type client_credentials

must be set to client_credentials

URI Template: /oauth/token?grant_type=client_credentials

Response 200

Headers
Content-Type: application/json
Payload
{
    "access_token": "ABCDE",
    "token_type": "bearer",
    "level": "app",
    "expires_in": null
}

Authorizations Endpoint

Given you have an App level token, this endpoint can be used to retrieve a list of schools that have authorized your application.

Request

GET /authorizations
Headers
Accept: application/vnd.assembly+json; version=1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYm

Response 200

Headers
Content-Type: application/json; charset=utf-8
Payload
{
    "object": "authorizations",
    "id": 35,
    "name": "Assembly Test",
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "prev_page": null,
    "next_page": null,
    "data": [
        {
        "object": "authorization",
        "school_id": 86,
        "school_name": "Elk Valley School for Boys 80",
        "school_urn": "KDVZEKJB"
        },
        {
        "object": "authorization",
        "school_id": 95,
        "school_name": "White Mountain Charter School 89",
        "school_urn": "EDDYOUGK"
        }
    ]
}

Authorization Code Exchange

Given you have an authorization code, this endpoint can be used to obtain an access token, along with a refresh token that you must also store.

Clients must provide their client_id and client_secret credentials via an HTTP Basic Authentication header.

Request

POST /oauth/token?grant_type=authorization_code&code={code}
Headers
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Parameter Default Example Description
grant_type authorization_code

must be set to authorization_code

code oehibebvero0v23

the authorization code obtained via a previous authorization request

redirect_uri https://example.com/callback

this value must exactly match your configured redirect URI

URI Template: /oauth/token?grant_type=authorization_code&code={code}

Response 200

Headers
Content-Type: application/json
Payload
{
    "access_token": "ABCDE",
    "refresh_token": "WXYZ",
    "token_type": "bearer",
    "level": "school",
    "expires_in": 108000,
    "school_id": 123,
    "scopes": ["school", "students"]
}

Refresh Token Exchange

Given you have a refresh token, this endpoint can be used to obtain a refreshed access token.

Clients must provide their client_id and client_secret credentials via an HTTP Basic Authentication header.

Request

POST /oauth/token?grant_type=refresh_token&refresh_token={refresh_token}
Headers
Accept: application/json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Parameter Default Example Description
grant_type refresh_token

must be set to refresh_token

refresh_token 34g9hp0obobgo9g23

the refresh token obtained via a previous authorization request

URI Template: /oauth/token?grant_type=refresh_token&refresh_token={refresh_token}

Response 200

Headers
Content-Type: application/json
Payload
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...",
    "token_type": "bearer",
    "level": "school",
    "expires_in": 108000,
    "school_id": 123,
    "scopes": ["school", "students"]
}

User Info End-Point

User info requests should be made to https://api.assembly.education or https://api-sandbox.assembly.education.

Given that you have a valid access token, this endpoint can be used to obtain some basic information about that token and it's access level.

Request

GET /me
Headers
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0sZZxr3r...

Response 200

Headers
Content-Type: application/json
Payload
{
  "level": "school",
  "app": {
    "id": 1,
    "name": "Your Application Name"
  },
  "school": {
    "id": 1,
    "urn": "A3786785",
    "name": "Example School Name",
    "slug": "example-school-name",
    "la_code": 123,
    "establishment_number": 1234,
    "phase": "Secondary",
    "scopes": ["school", "students"]
  }
}