---
url: https://flat.io/developers/docs/api/flat-for-education.md
---

# 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](#available-features-in-the-api)
* [Your first steps with our REST API](#your-first-steps-with-our-rest-api)
* [Interacting with other teachers and students' accounts](#interacting-with-other-teachers-and-students-accounts)
  * [Search user account ID](#search-user-account-id)
  * [Create access token for your end-user](#create-access-token-for-your-end-user)
  * [Use the delegated access token](#use-the-delegated-access-token)
* [Creating Sign-in links](#creating-sign-in-links)
  * [Search user account ID](#search-user-account-id-1)
  * [New sign-in link](#new-sign-in-link)

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](https://flat.io/developers/api/reference/#operation/createScore) in a user account.
* [Creating](https://flat.io/developers/api/reference/#operation/createOrganizationUser), [managing](https://flat.io/developers/api/reference/#operation/listOrganizationUsers), and [deleting](https://flat.io/developers/api/reference/#operation/removeOrganizationUser) students and teachers accounts.
* [Creating](https://flat.io/developers/api/reference/#operation/createClass), [accessing](https://flat.io/developers/api/reference/#operation/listClasses)  classes, and [managing rostering](https://flat.io/developers/api/reference/#operation/addClassUser).
* [Creating](https://flat.io/developers/api/reference/#operation/createAssignment) assignments, [submitting them as students](https://flat.io/developers/api/reference/#operation/createSubmission), and [exporting grades](https://flat.io/developers/api/reference/#operation/exportSubmissionsReviewsAsCsv).

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:

1. If you do not have a Flat for Education school account, [create one on our website](https://flat.io/edu).
2. Using your education account, [register a new app](https://flat.io/developers/apps). 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:

```http
Authorization: Bearer my-api-personal-access-token
```

Here is an example with cURL:

```bash
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](https://flat.io/help/en/education/invite-students.html) or [our API](https://flat.io/developers/api/reference/#operation/createOrganizationUser), [create a personal access token](https://flat.io/developers/apps) as explained above with the `edu.admin.users` authorization.

For the following examples, let's set our token in a shell variable

```bash
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`](https://flat.io/developers/api/reference/#operation/listOrganizationUsers) API method to search it:

```bash
curl 'https://api.flat.io/v2/organizations/users?q=student42@gedu.demo.flat.io' \
  -H "Authorization: Bearer $TOKEN"
```

```json
[
  {
    "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`](https://flat.io/developers/api/reference/#operation/createOrganizationUserAccessToken).

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:

```bash
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"]}'
```

```json
{
  "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:

```bash
export STUDENT_TOKEN=student-access-token

curl 'https://api.flat.io/v2/collections/root/scores' \
  -H "Authorization: Bearer $STUDENT_TOKEN"
```

```json
[
  {
    "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](https://flat.io/help/en/education/invite-students.html) or [our API](https://flat.io/developers/api/reference/#operation/createOrganizationUser), [create a personal access token](https://flat.io/developers/apps) as explained above with the `edu.admin.users` authorization.

For the following examples, let's set our token in a shell variable

```bash
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`](https://flat.io/developers/api/reference/#operation/listOrganizationUsers) API method to search it:

```bash
curl 'https://api.flat.io/v2/organizations/users?q=student42@gedu.demo.flat.io' \
  -H "Authorization: Bearer $TOKEN"
```

```json
[
  {
    "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`](https://flat.io/developers/api/reference/#operation/createOrganizationUserSigninLink):

```bash
curl -X POST 'https://api.flat.io/v2/organizations/users/STUDENT_USER_ID/signinLink' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```json
{
  "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](https://en.wikipedia.org/wiki/HTTP_302)).

Optionally you can provide a [`destinationPath`](https://flat.io/developers/api/reference/#operation/createOrganizationUserSigninLink), 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](https://flat.io/developers/api/reference/) about the REST API possibilities:

* [Scores](https://flat.io/developers/api/reference/#tag/Score) and [library collections](https://flat.io/developers/api/reference/#tag/Collection)
* [Flat for Education accounts management](https://flat.io/developers/api/reference/#operation/listOrganizationUsers)
* [Classes](https://flat.io/developers/api/reference/#operation/listClasses) and [assignments](https://flat.io/developers/api/reference/#operation/listAssignments).

Do you have some feedback about our product and APIs? Please contact our product team at <edu@flat.io>.