OAuth2 - JWT for Domain-wide Service Accounts

Saeko API can authorize enterprise applications to access resources owned by a domain administrator, without requiring explicit consent from a user. With a private key a third-party application can delegate authority to any user inside the domain.

Concepts

• Domain: In Saeko every customer owns a single domain. All data owned by the customer is available only inside of the domain.

• Client: (My Application Server) The third-party application that has access to the domain.

• Service Account: a private key used by the client to access the domain. These keys have an expiration date and should be renewed.

• User Account: an actual account created inside of Saeko; represented by an email and password.

• Authentication Server: Saeko has a single server that manage the OAuth2 protocol.

• API Server: Saeko has multiple servers hosting one or more domains.

• JSON Web Token: (JWT) is an open standard (RFC 7519). In this implementation Saeko creates an asymmetric RSA key pairs: a private key secured by the client (signs a JSON message), and a public key stored in Saeko (verifies the integrity of the JSON message). More information at https://jwt.io.

Requirements

For the client to access a domain it needs:

• 1) Service Account credentials: (ask our support team for credentials)

service_account:
  auth_url: "https://..."
  api_url: "https://..."
  client_id: "..."
  private_key_id: "..."
  private_key: "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  expires_at: "2021-01-01T00:00:00Z"

• 2) A user account to delegate authority to. Only the email is required.

  • This account must be created from the Administrator Portal in Saeko.
  • The permissions assigned to this user will be enforced when accessing the API with the Service Account.

Authentication Flow

How to create Access Token (Delegate Authority)

Request a token to the OAuth2 server with a JSON Web Token (JWT).

• Use the following values to build the JWT payload:

const payload = { 
  iss: `${client_id}`,
  sub: `${user_email}`,
  scope: "admin",
  iat: `${timestamp_epoch}`,
  jti: MD5(`${private_key_id}:${timestamp_epoch}`)
}

• client_id: from the service account.

• user_email: the email of the user you want to delegate access to.

• private_key_id: from the service account.

• timestamp_epoch: the server's Epoch time.

• Encode the JWT with your private key using RS256.

const jwt = JWS.sign(null, { 'typ': 'JWT', 'alg': 'RS256'}, payload, private_key);

• Build the request and use the encoded JWT in the body with Content-Type: application/json:

const response = await fetch(auth_url, {
  method: 'POST', 

  headers: {
    'Content-Type': 'application/json'
  },

  body: JSON.stringify({
    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "assertion": `${jwt}`
  })
})

The authentication server will validate the JWT and create an access token for the delegated user.

• If the delegated user does not belong to the domain, or is an invalid user, then a 401 Unauthorized error code will be returned.

This is and example of the body response:

{
  "access_token": "***",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "***",
  "scope": "admin",
  "created_at": 1577836800
}

• expired_in must be used to refresh the token before expiration.

• access_token must be used in all future API requests in the headers:

{ 'Authorization': `Bearer ${access_token}` }

How to refresh the Access Token

Just before the token expires or when receiving a 401 Unauthorized response from the API, try refreshing the access token.

Reasons for receiving a 401 Unauthorized response from the API:

• Token expired; most common.

• The user doesn't exists any more, or has been downgraded/deactivated.

• The API has denied access to the token/user.

To refresh the token make an OAuth2 request to POST /oauth/token with the body:

{
  "refresh_token": "***",
  "scope":"admin",
  "grant_type":"refresh_token"
}

Replace the access token and resume the API requests.

When the refresh token request replies with 401 Unauthorized, then the refresh token has been revoked and the client must invalidate and delete the access token object entirely.

The Saeko API is organized by resources following a REST Architecture design:

Resources in Saeko can be fetched, created, updated, and deleted using:

• an HTTP Method
• a URL that represents the resource and,
• a well defined resource/payload object

HTTP Headers

• Authentication: Bearer ... - Use the access token to authenticate the request.

• Content-Type: application/json; charset=utf-8 - When using POST or PUT the body must always be a JSON object.

HTTP Query Parameters

Resources are usually simple objects, but for efficiency and practicality you may find yourself in these situations:

• Need extra fields or objects embed inside of resources to avoid N+1 requests.

  • Use either fields or include_fields
  • fields - to specify exactly which fields you need from a resource.
  • include_fields - to request additional attributes; those marked with extra.
  • set the value in the form: ?include_fields=field_a,field_b,nested_object(field_x,field_y).
  • use only in endpoints that explicitly specifies support for fields.

• Filter, paginate, and sort a long list of data; sometime imposed by the API.

  • filters - filter a GET request.
    • set the value in the form of ?filters=field_a=1,2;boolean_field;association_object(field_a=1)
    • separate multiple filters with ;,
    • you can filter by multiple values, separate each one with ,; e.g. ?filters=status=1,2
    • boolean filters don't need values; e.g. ?filters=active
  • limit - activate pagination; e.g. ?limit=30
    • offset can help move the response to the next set of records; e.g. ?limit=20&offset=20
    • use this parameters only for endpoints that explicitly specifies support for pagination
    • some endpoints have pagination enforced.
  • sort_by - sort results; e.g. ?sort_by=created_at:desc
    • :asc and :desc are the only valid order values
    • the order is optional, as the default is :asc; e.g. ?sort_by=created_at
    • use this query parameter when doing pagination to get consistent results.

HTTP Response Codes

• 200 OK - Success.

• 204 No Content - A DELETE request successfully deleted the resource.

• 400 Bad Request - The request body or the path is malformed or inexistent.

• 401 Unauthorized - The access token has expired or is invalid.

• 403 Forbidden - The request is not accessible by the current user.

• 404 Not Found - The requested resource, or context, does not exist.

• 422 Unprocessable Entity - When using POST/PUT and there was an invalid field in the payload. Usually the response body will contain a simple explanation.

Common Error Descriptions

Error descriptions can be found in a JSON formatted response, e.g.:

{ "error_description": "Invalid Path" }

Example of common error descriptions:

• Invalid Path - The request URL PATH is invalid or inexistent. Example of invalid paths:

  • /api/v1/core/terms//students (the term_id is missing)
  • /api/v0/core/user (invalid API version)

• Malformed Payload - Happens when the request has a JSON payload that is malformed, e.g.:

  • { "students": { "name": "Name", } } (JSON object is invalid because there is an extra ",")

• Parameter required: ...- The payload MUST contain the specified value to continue.

  • Spanish: Parámetro obligatorio: ...

• Invalid parameter: ... - The payload contains a specific invalid value that should be fixed accordingly the resource documentation.

  • Spanish: Parámetro inválido: ...

• Unprocessable entity: ... - The payload contains general invalid values that can not be processed.

  • Spanish: Dato de entrada inválido: ...

• Resource not found: ... - May be an invalid context, or a resource in the payload that does not exist.

  • Spanish: Recurso no encontrado:

• Bad request - A reason is not specified, but there is something wrong with the client's request: either in the payload, or the PATH.

  • Spanish: Solicitud inválida

• Access forbidden - User is not allowed to perform this request until permissions are granted.

  • Spanish: Acceso restringido

• User unauthorized - The user credentials, access token in the Authentication header, are expired or inexistent. Renewing the access token should usually resolve this error.

  • Spanish: Usuario no autorizado

• Server error - Unspecified error in the server side.

  • Spanish: Error en el servidor

• Request not allowed - The request action (HTTP Method) cannot be executed to the resource or the context. This error can appear when updating a protected/locked resource.

  • Spanish: Solicitud no permitida

REST Methods - Examples

REST Methods - Examples (With Context)

Resource Payload

When doing a POST or PUT to create or update a resource you must always send a JSON object with the resource name in snake_case and singular:

E.g. to create a new student, the payload will be:

{
    "student": {
        "name": ""
        // ...
    }
}

Resource Payload - Multi

There are a few resources that support more than one resource to either create or update. In this case the request will be POST and the payload will have the resource name in plural.

E.g. to save multiple periods in a school term:

POST /api/v1/core/terms/:term_id/periods

{
    "periods": [
    {
        // use ID to update existing periods
        "id": 1,

        // updates the name for the existing period
        "name": "Period 1"
        },
        {
            // creates a new period with this name
            "name": "Period 2"
        }
    ]
}

{
    "period": {
      // THIS IS INVALID:
      "id": 1,

      "name": "Period 1"
  }
}

API Structure

Resources in SaekoAPI are structured in different namespaces and contexts that are represented by consistent URL Paths.

• namespace: is a group of resources that make sense together.

  • A namespace will have the form /api/v1/{namespace}
  • E.g. resources related to a geographical locations are found in the namespace /api/v1/location: Address, State and Country.

• context: is a parent resource that in a way provides context to other related resources.

  • A context path will have the form /api/v1/{namespace}/{context-resource-name}/{context-resource-id}/{resource}
  • E.g. To create a new student you must provide a Term as context: POST /api/v1/core/terms/:term_id/students (:term_id should be replaced with an actual ID).
  • Contexts are used by the API con control user access to resources as well as building requests that make more sense to the client.
  • ⚠️ If the context is invalid or inexistent the request will usually respond with 404 Not Found.

Notes Legend

• required

  • when creating a new object with POST: field value must be present and valid.
  • when updating an existing object with PUT: field value can't be nullified.

• read-only

  • fields only available on GET requests.

• write-only

  • fields can only be used in POST or PUT requests.
  • usually these fields are friendly substitutions to more complex data structures. E.g. student.mobile_phone will find in the phones array a record with type = MOBILE and update the phone_number, or create a new phone record.

• embed

  • fields that are objects and can be used in a POST/PUT request to save association records.
  • fields that are available in a GET request as embed associations.

• extra

  • fields that are not available by default in a GET request, and must be explicitly requested using ?include_fields=my_extra_field. See HTTP Query Parameters.

• association

  • can be belongs-to, has-one or has-many.
  • if the field name has a suffix _id, then this field must be the ID of associated object.
  • if combined with embed then the associated object can be found embedded in the payload; response (read-only), request (write-only) or both.

School

Model Definition

List of Endpoints

• GET  /api/v1/core/schools

  List all schools available to the current user.

  Allowed Users: adminapplicant
• GET  /api/v1/core/schools/id

  Show school by ID.

  Allowed Users: student

Term

Description

A Term in Saeko represents a School Year or Semester. Almost every process in Saeko are related to a single Term, e.g.: enrollments, groups, courses, payment plans, etc.

Model Definition

List of Endpoints

• GET  /api/v1/core/schools/school_id/terms

  List of terms filtered by a school-id

  Allowed Users: admin

Program

Description

A Program defines the school curricula. Students are usually enrolled every term on a specific program.

Model Definition

List of Endpoints

• GET  /api/v1/core/schools/school_id/programs

  List of programs filtered by school id

  Allowed Users: adminprofessorstudentapplicantsignee
• GET  /api/v1/core/terms/term_id/programs

  List of Programs filtered by Term.
  Terms and Programs are not directly associated, but the attributes term.school_id and term.term_type can filter programs.
  Useful when you only need programs compatible with a specific term.
  E.g. after fetching programs by term_id, you can then create a student's initial_enrollment with a program_id that is compatible with the term_id.

  Allowed Users: adminsignee
• GET  /api/v1/core/programs/id

  Show program by ID.

  Allowed Users: adminprofressorstudentapplicant
• POST  /api/v1/core/programs

  Add a program

  Allowed Users: admin

Group

Description

Students can be enrolled every school year into one and only one group. A group has a set of courses related to a single program. Students can enroll courses from the enrolled group, but also can enroll courses from other groups.

Model Definition

List of Endpoints

• GET  /api/v1/core/terns/term_id/groups

  List of groups by term id

  Allowed Users: admin
• GET  /api/v1/core/groups/id

  Group details, can include embed courses

  Allowed Users: admin
• POST  /api/v1/core/terms/term_id/groups

  Create group(s) in the specific term id. This endpoint supports multiple groups, which can be used not only to create new groups, but also to update existing groups.

  Allowed Users: admin
  Example:

  {
    "groups": [
        {
            // update existing group
            "id": 1,
            "name": "1A",
            "grade_level": 1,
            "program_id": 1,
            "shift": 1, 
            "max_students": 40,
            "default_room": "Aula 1",
            "status": 2
        },
        {
            // create new group
            "name": "1B",
            "grade_level": 1,
            "program_id": 1,
            "shift": 1, 
            "max_students": 40,
            "default_room": "Aula 2",
            "status": 2
        }
    ]
  }
  

Subject

Description

A Subject is part of a program or a multiple programs. Students are usually enrolled every term on a specific group of subjects.

Model Definition

List of Endpoints

• GET  /api/v1/core/programs/program_id/subjects

  List of subjects filtered by program id

  Allowed Users: admin
• GET  /api/v1/core/subjects/id

  Show subject by ID.

  Allowed Users: admin
• POST  /api/v1/core/subjects

  Create a new subject

  Allowed Users: admin

Course

Description

Courses are subjects that can be enrolled by students in a school year (term). Every course will belong to a group, therefor to a term and program.

Model Definition

List of Endpoints

• GET  /api/v1/core/terms/term_id/courses

  List of courses by term id. Pagination is enforced with a max limit of 100.

  Allowed Users: admin
• GET  /api/v1/core/groups/group_id/courses

  List of courses by group id

  Allowed Users: admin
• POST  /api/v1/core/groups/group_id/courses

  Create course(s) in the specific group. This endpoint supports multiple courses, which can be used not only to create new courses, but also to update existing courses.

  Allowed Users: admin

  Example:

  {
      "courses": [
      {
  
          "room": "Aula 1",
          "attendance_enabled": true,
          "professor_id": 1,
          "subject_id": 1
      },
      {
          // it's possible to update an existing course using the ID
          // it MUST belong to the same context group
          "id": 1,
          "room": "Aula 2"
      }]
  }
  

Student

Model Definition

List of Endpoints

• GET  /api/v1/core/terms/term_id/students

  List ACTIVE students filtered by `term_id`.
  The response objects contain a small set of fields; if more fields are required then use the GET student by id request.
  

  Allowed Users: admin
• GET  /api/v1/core/students/id

  Show student details.
  `include_fields` supported for extra fields.

  Allowed Users: adminprofessor
• GET  /api/v1/core/student

  Show the student if the current user is a student.

  Allowed Users: student
• POST  /api/v1/core/terms/term_id/students

  Create a new student with an initial enrollment in the `term_id`.
  **Query Params:**

  • `fields` `include_fields` - supported for extra fields.
  • `dry_run` - when `true` then the student object will be validated but not saved.
    • The `id` response will be `null`.
    • The `student_id` cannot be auto-generated.
  Allowed Users: admin
• PUT  /api/v1/core/students/id

  Update an existing student.
  `include_fields` supported for extra fields.

  Allowed Users: admin

Employee

Description

En employee is a person who belongs to one or more schools, and may have a role of Adminsitrator or Professor. To create a Professor just create an Employee with professor details. To create an Adminsitrator just create an Employee with the administrator role.

Model Definition

List of Endpoints

• GET  /api/v1/core/schools/school_id/employees

  List of employees that belongs to a school

  Allowed Users: admin
• GET  /api/v1/core/employees/id

  Show employee by ID.

  Allowed Users: admin
• POST  /api/v1/core/employees

  Create a new employee

  Allowed Users: admin

Contact

Model Definition

Address

Description

Saeko have a static database of all official places in Mexico.

Model Definition

State

Description

Saeko have a static database of all official cities in Mexico.

Model Definition

List of Endpoints

• GET  /location/countries/country_id/states

  List of states by Country

  Allowed Users: any

Country

Model Definition

List of Endpoints

• GET  /location/countries

  List of available countries

  Allowed Users: any

Scholarship

Model Definition

List of Endpoints

• GET  /api/v1/accounting/enrollments/enrollment_id/scholarship

  Get the enrollment belongs-to scholarship association object.

  Allowed Users: admin
• POST  /api/v1/accounting/enrollments/enrollment_id/scholarship

  Create a scholarship for the enrollment. Updates in case the enrollment has an existing scholarship record.

  Allowed Users: admin

ScholarshipType

Model Definition

List of Endpoints

• GET  /api/v1/accounting/scholarship_types

  List all available scholarship types; required when creating Scholarships.

  Allowed Users: admin

AdCampaign

Description

Basic catalog of advertising campaigns.

Model Definition

List of Endpoints

• GET  /api/v1/admissions/ad_campaigns

  List of ALL ad campaigns

  Allowed Users: admin

Activity

Model Definition

List of Endpoints

• GET  /api/v1/grading/courses/course_id/activities

  List of grading activities by course_id.

  Allowed Users: adminprofessorstudent

Grade

Model Definition

List of Endpoints

• GET  /api/v1/grading/courses/course_id/grades

  List of grades by course_id. This includes grades for all students in all activities in the course_id.

  Allowed Users: adminprofessor
• GET  /api/v1/grading/activities/activity_id/grades

  List of grades by activity_id. Smaller set of grade of all students of a single activity from a single course.

  Allowed Users: adminprofessor
• POST  /api/v1/grading/activities/activity_id/publish

  Save grades by activity_id.

  Allowed Users: adminprofessor
  Example:

  {
    "grades": [
      { "score": 10, "student_id": 16 }
      { "score": 9.1, "student_id": 17 }
      { "score": 5, "student_id": 18 }
    ]
  }
  

ExtraordinaryGrade

Model Definition

List of Endpoints

• GET  /api/v1/grading/courses/courses_id/extraordinary_grades

  List of extraordinay grades by course_id.

  Allowed Users: admin
• GET  /api/v1/grading/students/student_id/extraordinary_grades

  List of extraordinay grades by student_id.

  Allowed Users: admin
• POST  /api/v1/grading/courses/course_id/extraordinary_grades

  Save one or multiple extraordinay grades by course_id.
  When sending an array of extraordinary grades, is possible to update an existing record by sending his ID.

  Allowed Users: admin
  Example:

  {
    "extraordinary_grades": [
      { "score": "90", "student_id": 8023, "type": 1, "date": "2020-06-01" }
      { "id": 1234, "score": "80" }
    ]
  }
  

• DELETE  /api/v1/grading/courses/courses_id/extraordinary_grades/:id

  Remove an existing extraordinary grade.

  Allowed Users: admin

GateAccessLog

Model Definition

List of Endpoints

• POST  /api/v1/scheduling/gate_access_logs

  Record when a person access the gate using a card number.

  Allowed Users: admin
  Example:

  {
    "gate_access_log": {
      "card_number": "123456789",
      "direction": 1
    }
  }
  

User

Description

Students, professors, administrators and relatives can have credentials to access their respective portals.

These users can be created on external provisioning services: Google Suite or Microsoft Azure. (Special setup required)

When using the default provisioning services, user accounts are managed by Saeko and users must confirm the email address and setup a password.

Model Definition

List of Endpoints

• POST  /api/v1/provisioning/contactable_type/:contactable_id/user

  Create a user by contactable type: students, professors, relatives, administrators.

  E.g. POST /api/v1/provisioning/students/1/user

  E.g. POST /api/v1/provisioning/professors/1/user

  Allowed Users: admin