Authentication¶

Expiry of Sessions¶

User sessions will expire after a period of time. Once the session has expired you’ll receive a 403 Forbidden response. If you get a forbidden response then you need to obtain a new session id by either asking the user to login again using OAuth Authentication or by using a Refresh Token to obtain a new session id without intervention from the user.

Example Response When The Session has Expired:

HTTP/1.1 403 Forbidden
Cache-Control: no-cache
Content-Length: 142
Content-Type: application/json

{
  "ResponseStatus":
  {
    "ErrorCode": "Forbidden",
    "Message": "Your session is invalid or has expired",
  }
}

Redirect the user to the login page¶

You should redirect the user to https://signin.ecenglish.com/oauth with the following query string parameters

client_id

This should be the client id we provided when your site was setup to use OAuth

response_type

This should always be the value code

redirect_uri

This should be the URL you want the client to be redirected to once they’ve logged in. This must be exactly the same value that you provided when your client was setup.

state

This will be passed back to you as a parameter when the client is redirected back to your site. You should include an anti-forgery token as part of this value and validate it when the user is redirected back to your site

Example URL:

https://signin.ecenglish.com/oauth?client_id=client-333&response_type=code&redirect_uri=https://example.com&state=dfjlkdsfsks

When users are redirected back to your site¶

The users will be redirected back to the specified page on your site with the following query string parameters

state

This is the value that was passed to us.

code

This is a one time code that can be used to retreive a session id for the user

Once you’ve validated the anti-forgery token you added to the state parameter is valid you can convert the code value into a session id.

Converting a code into a session id¶

To convert the code value provided when the user was redirect back to your site into a session id, your website should perform a POST request to https://signin.ecenglish.com/oauth/token and provide the following parameters using the application/x-www-form-urlencoded content type.

grant_type

This must be the value authorization_code

code

The code provided by the redirect

client_id

The client id we provided when your site was setup using OAuth

client_secret

This is the value we provided when you were setup to use OAuth

redirect_uri

This must be exactly the same value that you provided when your client was setup. This is only used to validate your token request as your website should be POSTing to this endpoint directly

The response message will be a json object with the following fields:

access_token

This is the session id

token_type

This will be the value Bearer

scope

This will either be student or agent to indicate if the token is for a student or an agent

refresh_token

This allows you to obtain another access_token after the current one has expired without asking the user to login again.

Example Request:

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 118

client_id=client-333&grant_type=authorization_code&redirect_uri=https://www.example.com&code=dkdk&client_secret=cvjlkdf

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 107

{
    "access_token": "jkldfjdflk",
    "token_type": "Bearer",
    "scope": "agent"
}

Getting a users details using a session id¶

You can call the API to get the basic details of a logged in user:

** Example Request **

POST /oauth/token HTTP/1.1
Content-Type: application/json
Content-Length: 2
X-EC-Session: Bearer some-session-id

    {}

** Example Response for a student **

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 193

{
    "Id": "an-id",
    "FirstName": "John",
    "LastName": "Smith"
    "Email": "johnsmith@example.com",
    "StudentDetails": {
        "Id": 882
    }
}

** Example Response for a agent **

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 208

{
    "Id": "an-id",
    "FirstName": "Margery",
    "LastName": "Jones"
    "Email": "margeyjones@example.com",
    "AgentUserDetails": {
        "AgentCode": "A88",
        "OfficeCodes": ["O1"]
    }
}

** Example Response for Staff **

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 208

{
    "Id": "an-id",
    "FirstName": "Emily",
    "LastName": "Pankhurst"
    "Email": "emily@example.com",
    "StaffDetails": {
        "UserName": "x988"
    }
}

Obtaining a session id using a refresh token¶

You can convert your refresh_token value into a session id by performing a POST request to https://signin.ecenglish.com/oauth/token and provide the following parameters using the application/x-www-form-urlencoded content type.

grant_type

This must be the value refresh_token

refresh_token

The refresh token you wish to convert into a session id

client_id

The client id we provided when your site was setup using OAuth

client_secret

This is the value we provided when you were setup to use OAuth

The response message will be a json object with the following fields:

access_token

This is the session id

token_type

This will be the value Bearer

scope

This will either be student or agent to indicate if the token is for a student or an agent

refresh_token

You can use this value as a refresh_token to authenticate the user the next time you need a session (each refresh_token can only be used once)

Example Request:

POST /oauth/token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
Content-Length: 90

client_id=client-333&grant_type=refresh_token&refrsh_token=jkldfds8&client_secret=cvjlkdf

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 159

{
    "access_token": "jkldfjdflk",
    "token_type": "Bearer",
    "scope": "agent",
    "refresh_token": "new-refresh-token-value"
}

Dealing with a revoked refresh token¶

Refresh tokens can be revoked by the user. They will also be automatically revoked if they’ve not been used for a long period of time. If you try to use a revoked refresh token you’ll get a response like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 93

{
    "error": "Invalid refresh token",
    "error_description": "invalid_grant"
}

If you recive an invalid_grant response you’ll need to ask the user to login again to obtain a new refresh token.