This article is for DEVELOPERS.


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.


Learn more about the benefits of Snapplify Access here.


Authentication with Snapplify Access involves the following steps:

  • Registering your app to obtain a Client ID and Client Secret.
  • Getting a token to specify scopes or the permissions your app requires.
  • 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. Also, 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 following authentication flows:

Flow Type

Description

Implicit code flow

Your application does not use a server, such as a client-side JavaScript app or mobile app. This approach does not require a server that must make requests to the API.

Authorisation code flow

Your application uses a server, can securely store a Client Secret and can make server-to-server requests.

 

Sending user access tokens

When an API request requires authentication, send the following:

curl -H "Authorisation: 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:


'identity'.
This scope is available by default, and allows the users basic identity information.


'teacher'

This scope is only available to enterprise customers. It is used to identify if a user is a teacher within the Snapplify environment.

 

Getting access tokens

There are two OAuth procedures:

  • The OAuth implicit code flow gets user access tokens.
  • The OAuth authorisation code flow gets user access tokens.

OAuth implicit code flow


Step 1:
Send the user you want to authenticate to your registered redirect URI. Then, an authorisation page will ask the user to sign up or log into Snapplify and allow the user to choose whether to authorise your application/identity system or not.

Example Request:

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

There are several required and optional query-string parameters:


Required ParameterTypeDescription
client_idstringYour Client ID
redirect_uristring

Your registered redirect URI. This must exactly match the redirect URI registered in the prior registration step. For example https://website.com/login.

response_typestring

Specifies what information to return. This must be a token in order to return an access token. The user may be prompted to confirm authorisation once or repeatedly.

scopestring

A space-separated list of scopes.


Optional ParameterTypeDescription
statestring

Your unique token, generated by your application. This is an OAuth 2.0 opaque value used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.


In our example, you request access to a user’s basic information (by specifying the 'identity' scope) and send the user to localhost:

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


Step 2:

If the user authorises your application, the user is redirected to your redirect URL:

https://<your registered redirect URI>#access_token=<an access token>

The access token is in the URL fragment, not the query string, so it will not show up in HTTP requests to your server. URI fragments can be accessed from JavaScript with document.location.hash.


The response includes the state parameter if it was in your request.

In our example, your user gets redirected to:

https://localhost#access_token=0123456789abcdefghijABCDEFGHIJ
    &scope=identity
    &state=<your state param>
    &token_type=bearer


OAuth authorisation code flow

Step 1: 

Send the user you want to authenticate to your registered redirect URI. Then, 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/identity system.

Use this 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>

There are several required and optional query-string parameters:

Required Parameter

Type

Description

client_id

string

Your client ID.

redirect_uri

URL

Your registered redirect URI. This must exactly match the redirect URI registered in the prior registration step.

response_type

string

This must be code, causing an authorisation code to be returned, which is used later in this procedure. A given user is prompted to confirm authorisation only on the first request.

scope

string

A space-separated list of scopes.

 

Optional Parameter

Type

Description

state

string

Your unique token, generated by your application. This is an OAuth 2.0 opaque value used to avoid CSRF attacks. This value is echoed back in the response. We strongly recommend you use this.


In our example, you request access to a user’s basic information
(by specifying the 'identity' scope) and send the user to http://localhost:

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:

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

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


The OAuth 2.0 authorisation code is a 30-character, randomly generated string. It is used in the next step – a request made to the token endpoint in exchange for an access token.


The response includes the state parameter if it was in your request.


In our example, your user gets redirected to:

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


Get an access token on your server by making this request:

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>


We respond with a JSON-encoded access token. The response looks like this: 

{
  "access_token": "<user access token>",
  "refresh_token": "<refresh token>",
  "expires_in": <number of seconds until the token expires>,
  "scope": ["<your previously listed scope(s)>"],
  "token_type": "bearer"
}


 

Code examples

Snapplify implements standard OAuth 1(a) and OAuth 2.0 protocols and as such, all standard libraries can be used to integrate. Take a look at the many libraries available to developers oauth.net/code/.


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

The next step requires you to get the auth token, to make additional authenticated calls:

curl -H 'Accept: application/json' \
-H 'Authorisation: Bearer <Access Token>\
-X GET 'https://auth.snapplify.com/api/userinfo'


Depending on which scope was requested, and allowed, you would get different information.

Example with only the 'identity' scope.

{
"id": 123456789,
"name": "John Doe",
"given_name": "John",
"family_name": "Doe",
"username": "testuser",
"email": "john@doe.co.za",
"email_verified": false,
"picture": "http:// ..."
}

Example with the 'roles' scope. (note the addition of the roles information)

{
    "id": ...
    "teacher_verified": true,
    "teacher": true
}


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

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



Branding guidelines

Usage of the Snapplify sign-in button should be consistent with other sign-in options, with equal prominence and size.


Image

Details

 

This button needs to be the same height and width as other buttons used for OAuth purposes.

The SnappStar logo can be retrieved here: 

https://cdn.snapplify.com/latest/img/snappstar.png

 

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