API Authentication

See also: Full API Documentation

Get your access

If you wish to go further with the API and modify the data in the database, you will need to allow your user to authenticate.

To do that, you will need a registered application on our website. Contact us with the following info:

Username on School Idol Tomodachi: 
Twitter handle: 
Best way to contact you: 
Name of your app: 
App description: 
Why do you need authentication?: 
Redirect URIs: 
App technologies: 
Is the authentication client side or server side?: 

Example:

Username on School Idol Tomodachi: db0
Twitter handle: @dbschoolidol
Best way to contact you: Twitter DMs
Name of your app: MySuperApp
App description: A website that shows one different random card from LLSIF everyday
Why do you need authentication?: I want to add a button to add the cards to wish list on School Idol Tomodachi
Redirect URIs: http://mysuperapp.com/oauthredirect/
App technologies: RoR for backend + Angular JS for frontend
Client side / Server side?: Everything is going to be done server side in Ruby on Rails

Notes:

• You can provide multiple URIs if needed.
• Your app name may contain spaces and special ASCII characters (no emojis or other weird characters)

We will take the time to talk to you and send you your access information. We will also help you get started and reply to any question you might have. We will also help you optimize your requests to the API to make sure you get what you want the most efficient way.

Authentication

We use OAuth2.

OAuth2 allows you to GET / POST / PATCH / DELETE data on the behalf of a user using tokens. The scenario to get tokens is not as simple as just a username and password, but it allows us to provide this service without allowing third parties to have access to users' passwords, which would be a big security issue.

• By default, the grant type is going to be an authorization code: Follow the scenario

• If your application runs client-side (javascript, native software or mobile apps), the grant type is going to be a token: Follow the scenario

Authorization code

• Link to https://schoolido.lu/o/authorize/?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

• The user will have to login or create an account (if not logged in), then authorize your application:

• The user will then be redirected to your redirect URI with a GET parameter code. Example http://mysuperapp.com/oauthredirect/?code=1234

• Perform a POST request to https://schoolido.lu/o/token/ with the following POST data:

grant_type=authorization_code
&code=CODE_YOU_JUST_GOT_IN_GET_PARAMETERS
&redirect_uri=YOUR_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

• The response will be a JSON object that contains the following data:

{
  "access_token": "x1V38GSike9MA3vZSpzCrV63D0fAud",
  "token_type": "Bearer",
  "expires_in": 36000,
  "refresh_token": "yaCa9QgoQOlzN09pRRp2i8S8hTrBBi",
  "scope": "read write"
}

• To make authenticated requests to the API, add the following HTTP header: Authorization: Bearer ACCESS_TOKEN

Token expiration & refresh token

After the number of seconds in expires_in passed, your access token will not be valid anymore. To get a new token without asking the user to accept again, you can use the refresh token that you got the first time you authenticated.

• Perform a POST request to https://schoolido.lu/o/token/ with the following POST data:

grant_type=refresh_token
&code=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

• The response will be a JSON object similar to the one you got the first time you authenticated. It will contain a new refresh token that you can use in the future, and the refresh token you just used will become invalid.

Token

• Link to https://schoolido.lu/o/authorize/?response_type=token&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

• The user will have to login or create an account (if not logged in), then authorize your application:

• The user will then be redirected to your redirect URI with a fragment (also known as "named anchor", corresponds to the part of the URL after a "#") that contains the following data:

access_token=Hg5rpgUumzoWAJhaFUkEtdl4YqgcoQ
&token_type=Bearer
&state=
&expires_in=36000
&scope=read+write

• To make authenticated requests to the API, add the following HTTP header: Authorization: Bearer ACCESS_TOKEN

Sample apps

• Python (simple Django website)
• PHP

Keep in mind that implementing an OAuth scenario yourself is generally not a good idea, so you should search for nice OAuth client libraries that will do the job for you.

Notes

• Only supports basic key/value data formatting or multi-part when uploading images.
• To send a boolean, use True or False.
• Dates are formatted like this: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z] example: 2015-02-15T08:00

Methods

Methods are added when people ask for them, so if there's something that you can do on the site but not with the API, just Contact us and we'll add it.

1. Users
   1. Get the authenticated user
   2. Follow a user
   3. Unfollow a user
2. Owned Cards
   1. Note regarding adding/editing owned cards
   2. Add an owned card
   3. Edit an owned card
   4. Delete an owned card
3. Activities
   1. Note regarding likes
   2. Post an activity
   3. Edit an activity
   4. Delete an activity
   5. Like an activity
   6. Unlike an activity