Integrating Snapplify Access for Single Sign On (SSO)

Snapplify Access enables users to get instant and convenient access to your services. With Snapplify Access, signing in is as simple as clicking a button. SSO is part of the basic offering; for more complex Roster data, you will need to upgrade to a paid version of Access.

Learn more about the benefits of Snapplify Access here.

Setting up SSO involves the following steps:

1. Registering your app to obtain a Client ID and Client Secret.
2. Getting a token to specify scopes or the permissions your app requires.
3. Sending the token in your API request to authenticate API requests.

Registration

To make an application that uses the Snapplify API, you first need to request your application credentials from our team at help@snapplify.com. When requesting this app, you must specify your redirect URI, which is where your users are redirected after being authorised.

Once the application has been created, you will be sent a Client ID and Client Secret:

• Client IDs are public and can be shared (e.g. embedded in the source of a web page).
• Client Secrets are equivalent to a password for your application and must be kept confidential. Never expose it to users, even in an obscured form.

Your Client Secret is confidential, which means we cannot recover it, so make sure to record it somewhere safe. Generating a new Client Secret immediately invalidates the current one, which might make your API requests fail until your app is updated.

Getting Tokens

The domain dedicated to Snapplify Access is auth.snapplify.com.

We support the authorisation code flow:

Note: The implicit flow (response_type=token) is no longer supported. All clients must use the authorisation code flow (response_type=code). If you were previously using response_type=token, update your integration to use response_type=code and exchange the authorisation code for an access token via the token endpoint.

Sending User Access Tokens

When an API request requires authentication, send the following:

curl -H "Authorization: Bearer <access token>" https://auth.snapplify.com/api/userinfo

Scopes

When you request authorisation from users, the scope parameter allows you to specify which permissions your app requires. These scopes are tied to the access token you receive on successful authorisation. Without specifying scopes, your app can access only basic information about the authenticated user.

Snapplify currently supports the following scopes:

Access Basic

• identity — This scope is available by default, and allows access to the user's basic identity information.

Access Professional or Enterprise

• teacher — Determines if a user is a teacher within the Snapplify platform. Also includes additional information about the school.
• learner — Identifies if a user is a learner within the Snapplify environment. Also includes additional information about the school, grade, and classes.

OAuth Authorisation Code Flow

Step 1: Redirect the user to authorise

Send the user you want to authenticate to your registered redirect URI. An authorisation page will ask the user to sign up or log in to Snapplify, and allow the user to choose whether to authorise your application.

Request:

GET https://auth.snapplify.com/oauth/authorize
    ?client_id=<your client ID>
    &redirect_uri=<your registered redirect URI>
    &response_type=code
    &scope=<space-separated list of scopes>

Required parameters:

Optional parameters:

Example:

GET https://auth.snapplify.com/oauth/authorize?response_type=code&client_id=<your client ID>&redirect_uri=http://localhost&scope=identity&state=<your state param>

Step 2: Receive the authorisation code

If the user authorises your application, they are redirected to your redirect URI with an authorisation code:

https://<your registered redirect URI>/?code=<authorisation code>

The authorisation code is a randomly generated string used in the next step to exchange for an access token. The response includes the state parameter if it was in your request.

Example redirect:

https://localhost/?code=0123456789abcdefghijABCDEFGHIJ
    &scope=identity
    &state=<your state param>

Step 3: Exchange the code for an access token

Make a server-to-server request to exchange the authorisation code for an access token:

POST https://auth.snapplify.com/oauth/token
    ?client_id=<your client ID>
    &client_secret=<your client secret>
    &code=<authorisation code received above>
    &grant_type=authorization_code
    &redirect_uri=<your registered redirect URI>

Response:

{
  "access_token": "<user access token>",
  "refresh_token": "<refresh token>",
  "expires_in": 3600,
  "scope": "identity",
  "token_type": "bearer"
}

API Reference

For a complete interactive API reference, see the Snapplify Auth API documentation on Postman.

Code Examples

Snapplify implements the OAuth 2.1 standard, so all standard libraries can be used to integrate. Take a look at the many libraries available to developers at oauth.net/code/.

User Info API

The User Info API allows access to basic user information and is used to integrate Snapplify Access into your own applications.

Request:

curl -H 'Accept: application/json' \
     -H 'Authorization: Bearer <access token>' \
     -X GET 'https://auth.snapplify.com/api/userinfo'

Depending on which scope was requested and allowed, you will receive different information.

Example: identity scope

{
    "id": 1,
    "email": "placeholder@email.com",
    "name": "John Doe",
    "username": "JohnDoe25@",
    "given_name": "John",
    "family_name": "Doe",
    "picture": "https://via.placeholder.com/96",
    "mobileNumber": null,
    "email_verified": false,
    "emailVerified": false,
    "authorities": []
}

Example: teacher or learner scope

Note the addition of role and school information:

{
  "teacher": true,
  "teacher_verified": true,
  "school": {
      "id": 1,
      "name": "School Name",
      "url": "https://schoolname.snapplify.com/",
      "createdDate": "2017-11-16T11:48:09.000Z",
      "updatedDate": "2023-05-17T07:19:20.000Z"
  },
  "grade": {
      "id": 11,
      "name": "Grade 10",
      "createdDate": "2018-10-25T12:51:02.000Z",
      "updatedDate": "2022-10-08T20:05:57.000Z"
  },
  "class": [
      {
          "id": 11377,
          "name": "Grade 10 English Class",
          "createdDate": "2022-03-29T09:47:34.000Z",
          "updatedDate": "2022-03-29T09:47:34.000Z",
          "grade": {
              "id": 11,
              "name": "Grade 10",
              "description": "Grade 10",
              "createdDate": "2018-10-25T12:51:02.000Z",
              "updatedDate": "2022-10-08T20:05:43.000Z"
          }
      }
  ]
}

Linking to your application

Typically, you will use this data to link to a user record in your application:

{
  "authId": "1",
  "authType": "snapplify",
  "userId": "<a userid in your application>"
}

Branding Guidelines

See SSO Branding Guidelines.

You can also integrate Snapplify Access on WordPress or Moodle for SSO.

Need Help?

Use the live chat in the bottom right corner of your screen or email us at help@snapplify.com.