Documentation


Overview | Postman | OAuth | Endpoints

 

OAuth

  1. Web Application Flow
  2. Redirect URLs
  3. Common errors for the authorization request
  4. Common errors for the access token request

OAuth2 is a protocol that lets external apps request authorization to resources in a user's Schooltas account without getting their password.

All developers need to register their application before getting started. Contact us for registration. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

Web Application Flow

This is a description of the OAuth2 flow from 3rd party web sites.

1. Redirect users to request Schooltas access

GET https://api.schooltas.net/login/oauth/authorize

Parameters

Name Type Description
client_id string Required. The client ID you received from Schooltas when you registered.
redirect_uri string The URL in your app where users will be sent after authorization. See details below about redirect urls.
state string An unguessable random string. It is used to protect against cross-site request forgery attacks.

2. Schooltas redirects back to your site

If the user accepts your request, Schooltas redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

Exchange this for an access token:

POST https://api.schooltas.net/login/oauth/access_token

Parameters

Name Type Description
client_id string Required. The client ID you received from Schooltas when you registered.
client_secret string Required. The client secret you received from Schooltas when you registered.
code string Required. The code you received as a response to Step 1.
state string The unguessable random string you optionally provided in Step 1.

Response

The response will take the following form:

{
  "access_token": "1337|schooltasapi|8f2ae3f8-f69b-48f4-a91b-bc1610dad7d5",
  "scope": "",
  "token_type": "bearer"
}

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user. You can pass the token in the Authorization header

Authorization: Bearer OAUTH-TOKEN

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.schooltas.net/v1/books?ean=EAN

Redirect URLs

The redirect_uri parameter is optional. If left out, Schooltas will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL’s host and port must exactly match the callback URL. The redirect URL’s path must reference a subdirectory of the callback URL.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

Common errors for the authorization request

There are a few things that can go wrong in the process of obtaining an OAuth token for a user. In the initial authorization request phase, these are some errors you might see:

Application Suspended (not yet implemented)

If the OAuth application you set up has been suspended (due to reported abuse, spam, or a mis-use of the API), Schooltas will redirect to the registered callback URL with the following parameters summarizing the error:

http://your-application.com/callback?error=application_suspended
  &error_description=Your+application+has+been+suspended.
  &state=xyz

Please contact us to solve issues with suspended applications.

Redirect URI mismatch

If you provide a redirect_uri that doesn’t match what you’ve registered with your application, Schooltas will redirect to the registered callback URL with the following parameters summarizing the error:

http://your-application.com/callback?error=redirect_uri_mismatch
  &error_description=The+redirect_uri+MUST+match+the+registered+callback+URL+for+this+application.
  &state=xyz

To correct this error, either provide a redirect_uri that matches what you registered or leave out this parameter to use the default one registered with your application.

Access denied (not yet implemented)

If the user rejects access to your application, Schooltas will redirect to the registered callback URL with the following parameters summarizing the error:

http://your-application.com/callback?error=access_denied
  &error_description=The+user+has+denied+your+application+access.
  &state=xyz

There’s nothing you can do here as users are free to choose not to use your application. More often than not, users will just close the window or press back in their browser, so it is likely that you’ll never see this error.

Common errors for the access token request

In the second phase of exchanging a code for an access token, there are an additional set of errors that can occur.

Missing client credentials

If the client_id or client_secret or code is missing you will receive an error response like this:

{
  "error": "MissingClientCredentials",
  "message": "Client credentials are missing"
}

To solve this error, go back and make sure you have the correct credentials for your OAuth application. Double check the client_id and client_secret to make sure they are correct and being passed correctly to Schooltas.

Incorrect client credentials

If the combination of code, state, client_id and client_secret is invalid you will receive an error response like this:

{
  "error": "InvalidClientCredentials",
  "message": "Client credentials are invalid"
}