Using our APIs with Flat for Education
Our REST API is the perfect solution to interact with your Flat for Education accounts and extend the capabilities of our platform. Let’s discover on this page how to take full advantage of its features.
In this page:
- Available features in the API
- Your first steps with our REST API
- Interacting with other teachers and students’ accounts
- Creating Sign-in links
Any questions? Please contact our team at edu@flat.io.
Available features in the API
Our web and mobile applications use the same API we make available to our customers, which means most of our platform features can be used programmatically.
For example:
- Creating a new score or import a new score file in a user account.
- Creating, managing, and deleting students and teachers accounts.
- Creating, accessing classes, and managing rostering.
- Creating assignments, submitting them as students, and exporting grades.
Let’s discover below how to get started with our API.
Your first steps with our REST API
To get started with our Flat for Education API:
- If you do not have a Flat for Education school account, create one on our website.
- Using your education account, register a new app. Then on the left menu, choose “Flat API > Personal Tokens”. Choose a name and the authorization scopes for your first token.
That’s all, you can directly use our API with this token by setting it in the Authorization headers of your requests:
Authorization: Bearer my-api-personal-access-token
Here is an example with cURL:
curl -H 'Authorization: Bearer <my_api_personal_access_token>' \
https://api.flat.io/v2/me
Interacting with other teachers and students’ accounts
Our education REST API includes an endpoint that lets you create delegated access tokens. These tokens let you interact with our product as another teachers or students without any user interaction required. For example, you could automatically create classes or assignments for your teachers or create or upload scores in your students’ accounts.
Once you created a student or teacher account whether with our interface or our API, create a personal access token as explained above with the edu.admin.users authorization.
For the following examples, let’s set our token in a shell variable
export TOKEN=my-api-personal-access-token
Search user account ID
If you do not know the unique identifier of the student/teacher account, you can use the GET /v2/organizations/users API method to search it:
curl 'https://api.flat.io/v2/organizations/users?q=student42@gedu.demo.flat.io' \
-H "Authorization: Bearer $TOKEN"
[
{
"id": "STUDENT_USER_ID",
"type": "user",
"organizationRole": "user",
"classRole": "student",
"username": "tony",
...
}
]
Create access token for your end-user
Now create an access token for this student using your admin API endpoint POST /v2/organizations/users/{user}/accessToken.
For example with the scores authorization scope to be able to create new scores in the student’s account and collections to access to their library:
curl -X POST 'https://api.flat.io/v2/organizations/users/STUDENT_USER_ID/accessToken' \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"scopes": ["scores", "collections"]}'
{
"id": "61a4bc9750724f0013fdc7fd",
"name": "Access token created by organization admin",
"token": "An access token for your student account",
"issuedDate": "2021-11-29T11:42:15.475Z",
"expirationDate": "2021-11-30T11:42:15.475Z",
"scopes": [
"scores",
"collections"
]
}
Use the delegated access token
With the newly created access token, you can interact with the end-user account without any user interaction needed. For example, you can list your student library:
export STUDENT_TOKEN=student-access-token
curl 'https://api.flat.io/v2/collections/root/scores' \
-H "Authorization: Bearer $STUDENT_TOKEN"
[
{
"id": "615adeb58e4ed600136ab31d",
"title": "My first assignment - Tony Morris",
"privacy": "private",
....
},
....
]
Creating Sign-in links
Our education REST API includes an endpoint that lets you create sign in links for your users. They can typically be used to redirect your end-users to our platform while connecting them.
Once you created a student or teacher account whether with our interface or our API, create a personal access token as explained above with the edu.admin.users authorization.
For the following examples, let’s set our token in a shell variable
export TOKEN=my-api-personal-access-token
Search user account ID
If you do not know the unique identifier of the student/teacher account, you can use the GET /v2/organizations/users API method to search it:
curl 'https://api.flat.io/v2/organizations/users?q=student42@gedu.demo.flat.io' \
-H "Authorization: Bearer $TOKEN"
[
{
"id": "STUDENT_USER_ID",
"type": "user",
"organizationRole": "user",
"classRole": "student",
"username": "tony",
...
}
]
New sign-in link
Now create a sign in link for this end-user using your admin API endpoint POST /v2/organizations/users/{user}/signinLink:
curl -X POST 'https://api.flat.io/v2/organizations/users/STUDENT_USER_ID/signinLink' \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{}'
{
"url": "https://flat.io/auth/signin-link/xxxxxxxxxxxxxxxxxxx?next=%2F",
"expirationDate": "2021-11-30T13:12:09.783Z"
}
The returned URL can be used once by your end-user to sign in. We recommand to use it in a HTTP Temporary Redirect (302).
Optionally you can provide a destinationPath, for example, to redirect the user to a specific assignment or score once logged in.
Discover the API
Check out our API reference to learn more about the REST API possibilities:
Do you have some feedback about our product and APIs? Please contact our product team at edu@flat.io.