Getting Started

In order to access the BetterLesson API endpoints, clients will need to get an authorization code. This code should be then used to retrieve an access token and a refresh token. Client will be able to use the access token to access all endpoints until the token expires, at which point, clients will need to use the refresh token to get a new access token to continue to have access to the API endpoints. All these steps are explained in detail below.

Retrieving the Authorization Code

The URL used when authenticating a user is https://api.betterlesson.com/oauth2/auth. This endpoint is accessible over SSL. Non-secure HTTP connections are refused.

Endpoint	Description
https://api.betterlesson.com/oauth2/auth	This endpoint is the target of the initial request. It will return an authorization code for the client_id provided, and it can also authenticate users and get their consent. The result of requests to this endpoint will be authorization codes.

The set of query string parameters supported are:

Parameters	Values	Description
client_id	The client ID you obtain from BetterLesson.	Identifies the client that is making the request.
access_type	public (default) or private	Determine if the client can access the grantor’s private data.

An example URL is shown below:

https://api.betterlesson.com/oauth2/auth?client_id=dio32fiocg09j4g

If the access_type requested is public, the authorization code or any error messages will be in the response to the /oauth2/auth endpoint request.

An example response for a 'public' access_type:

{
   "code":"1/sdiojvaerjq3jf34verveoioijnw"
}

If, however, the access_type requested is private, the authorization request or any error messages will be sent to the redirect_uri set when your client credentials were created. You may change this uri by contacting BetterLesson support. All responses are returned to the web server on the query string, as shown below:

An example response for a 'private' access_type:

https://demo.app.com/code?code=1%2Favoi49joqierjv9q0483uf

Authorization codes expire in 10 minutes. Make sure to retrieve your access token before the expiration.

Retrieving an Access Token

After the client receives the authorization code, it may exchange the authorization code for an access token and a refresh token. This request is an HTTPS POST, and includes the following parameters:

Field	Description
code	The authorization code returned from the initial request.
client_id	The client ID obtained from BetterLesson.
client_secret	The client secret obtained from BetterLesson.
grant_type	As defined in the OAuth 2.0 specification, this field must contain a value of ‘authorization_code’.

The actual request might look like the following:

POST /oauth2/token HTTP/1.1
Host: api.betterlesson.com
Content-Type: application/x-www-form-urlencoded
 
code=1%2Favoi49joqierjv9q0483uf&client_id=do32fiocg09j4g&client_secret{client_secret}&grant_type=authorization_code

A successful response to this request contains the following fields:

Field	Description
access_token	The token that can be sent to a BetterLesson API endpoint.
refresh_token	A token that may be used to obtain a new access token. Refresh tokens are always valid for public access, and for private access they are valid until the user revokes access.
expires	UTC timestamp of when the access_token will expire.

A successful response is returned as a JSON array, similar to the following:

{
   "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
   "refresh_token":"1/ijoiwejqpeorjv209u3jp32EWCe9",
   "expires": <datetime>
}

Access tokens expire one week after being issued. Make sure to use the refresh token to retrieve a new token upon expiration.

Calling a BetterLesson API Endpoint

After your application obtains an access token, you can use the token to make calls to a BetterLesson API endpoint. To do this, include the access token in a request to the API by including either an access_token query parameter or an Authorization: Bearer HTTP header. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs.

Examples

A call to the search endpoint using the access_token query string parameter might look like the following, though you'll need to specify your own access token:

GET https://api.betterlesson.com/search?keyword=algebra&access_token=1%2FfFBGRNJru1FQd44AzqT3Zg

Here is a call to the same API using the access_token ‘Authorization: Bearer’ HTTP header:

GET /search?keyword=algebra HTTP/1.1
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg
Host: api.betterlesson.com

Using a Refresh Token

Your application may obtain a new access token by sending a refresh token to the BetterLesson Authorization server.

To obtain a new access token this way, your application sends an HTTPS POST request to https://api.betterlesson.com/oauth2/token. The request must include the following parameters:

Field	Description
refresh_token	The refresh token returned from the authorization code exchange.
client_id	The client ID obtained from BetterLesson.
client_secret	The client secret obtained from BetterLesson.
grant_type	As defined in the OAuth 2.0 specification, this field must contain a value of ‘refresh_token’.

Such a request will look similar to the following:

POST /oauth2/token HTTP/1.1
Host: api.betterlesson.com
Content-Type: application/x-www-form-urlencoded

client_id=do32fiocg09j4g&client_secret={client_secret}&refresh_token=1%2Fijoiwejqpeorjv209u3jp32EWCe9&grant_type=refresh_token

As long as the access granted to your application has not been revoked by BetterLesson or by the user, the response includes a new access token. A response from such a request is shown below:

{
   "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
   "refresh_token":"1/ijoiwejqpeorjv209u3jp32EWCe9",
   "expires": <datetime>
}

You should save refresh tokens in long-term storage and continue to use them as long as they remain valid.