User Authentification#

These endpoints are designed to grand access to the protected APIs for the end users of the astrology apps.

General APIs

  • /api/auth/obtain-jwt/ Issue the auth token, which grant access to protected APIs
  • /api/auth/verify-jwt/ Verify if the authentication token is valid

Teachable related APIs

  • /api/auth/teachable/ Redirects teachable calls.
  • /api/auth/teachable/token/ Otains or refreshes the user's access token on Teachable
  • /api/auth/teachable/verify-user/ Verifies user's access right on Teachable

General APIs#

These APIs are intended for applications developed by us that interact with this backend. Data protection is ensured by having our applications sign the data with a checksum using the same algorithm as this backend server. Therefore, the mandatory field for all authorization requests is the hash sum.

Token - Issue#

/api/auth/obtain-jwt/

Use this endpoint to authenticate a user in a front-end application. When accessing this URL, an authorized user receives a JSON web token, which is then used in headers for granting accesses to protected endpoints.

The token contains information about the user's access level to the API, as well as the expiration date. After 24 hours, the token expires, and the authorized user should use this endpoint again to obtain a new token.

Request#

Method POST

Value Type Comment
email str Email is used as user ID
level str The User's access level (as described here)
timestamp str A timestamp (in seconds), when the frontend App has generated the auth data
hash_value str A string with hash sum of the payload data

Authorization data, including a hash, is generated on the server, in the user's personal account, where he pays for the use of the front-end application.

A hash is an electronic signature that confirms that a given user is authorized to receive a 24-hour access token according to their access level.

Response#

Success status 200

{
    "email": "user@email.com",
    "level": "1",
    "exp": 1690327271.0,
    "Authorization": "eyJh..." // token
}

Failure status 400 (Bad Request)

{
    "error": [
        "error message"
    ]
}

Possible error messages:

  • Level format is incorrect.
  • Payload data is outdated. (the timestamp is older or younger than 24 hours)
  • Hash is invalid.

Token - Validation#

/api/auth/obtain-jwt/

The token provided in is a JSON Web Token, which should be used in Authorization field of HTTP request. You can always check if the token is valid by requesting this endpoint.

Method GET:

Header Type Comment
Authorization str JSON Web Token

Responce status 200:

{
    "email": "user@email.com",
    "level": "1",
    "exp": 1690327828.0
}

Responce status 400 (Bad Request):

{
    "error": [
        "error message"
    ]
}

Possible error messages:

  • Token has expired. (you need to obtain a new one in /api/auth/obtain-jwt/)
  • Token is invalid.

These APIs are used to integrate our applications with the Teachable platform. OAuth Teachable serves as the foundation for authorizing applications and users, as described in this article.

Redirect API#

/api/auth/teachable/

This is a technical API specified as the redirect_url when registering our applications in Teachable. After authorizing the corresponding frontend application, Teachable redirects the user to this endpoint. Depending on the state parameter in the GET request, the user is further redirected to the frontend application they just authorized in Teachable.

The redirect includes a parameter called code, which is the authorization code for the frontend application for a given user. This code is passed to the frontend application and used in the next step.

Obtain/Refresh User's Access Token#

/api/auth/teachable/token/

The frontend application can exchange the obtained authorization code for access tokens specific to a particular user only once. All subsequent requests to Teachable will occur on behalf of the user using their access token.

Request#

Method POST

Value Type Comment
action str use obtain use to exchange the app auth code to the user's access token. Use refresh to refresh the user's access token
code str use the code when action=obtain. This code is received fron the Teachable with use of /api/auth/teachable/ endpoint
refresh_token str use it with action=refresh
Response#

Success status 200

{
    "refresh_token": "xyz456",
    "token_type": "bearer",
    "access_token": "abc123",
    "expires_in": "7200"
}

Failure status 400 (Bad Request)

{
    "error": "error message"
}

Verify User#

/api/auth/teachable/verify-user/?

This API checks a student's access rights to applications on Teachable and returns either an empty token or a token along with access rights data.

Request#

Method POST

Value Type Comment
access_token str the user's access token for Teachable
app str Use natal or horary to identify the app to which you want to examine the user's access.
Response#

Success status 200

{
    "email": "user@email.com",
    "level": "1",
    "exp": 1690327271.0,
    "Authorization": "eyJh..." // token
}

Failure status 400 (Bad Request)

{
    "error": "error message"
}