Refresh token endpoint

The refresh token endpoint is a simple mechanism for enabling JavaScript applications to utilize SSO tokens and SSO login URLs that are securely generated by your server.

A refresh token endpoint is implemented by creating a new URL in your application. For example:

https://app.yourcompany.com/refresh_token.php

The refresh token should return a JSON string and an appropriate HTTP status code to indicate success or failure. By requesting the endpoint via AJAX, your JavaScript code can access the SSO tokens and SSO login URLs that were securely generated by your server.

Note

By generating the token on the server your Private Key is kept safe and you can avoid many of the security pitfalls of implementing SSO in purely client-side JavaScript.

You should also only serve the endpoint over SSL to prevent man-in-the-middle attacks on your endpoint.

Successful response

This response should be sent if the user if logged into your system and you have granted them access to the Chargely billing portal.

HTTP headers

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

HTTP body (JSON)

{
    "status": "success",
    "data": {
        "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJLV2VVdkI5elJWcmYxdEZhTUdsZ29UVFppRDFOcUlnTiIsImlhdCI6MTQyOTU3NTk3NiwiYXVkIjoiLSIsImN1c3RfZW1haWwiOiJjaGFyZ2VseV8xMzM0NTAyNjUzQG1haWxpbmF0b3IuY29tIn0.YjaHf_o6qdicx51ziZKwB9oErpCLr3Ze7Pq6j_qrpPo",
        "sso_login_url": "https:\/\/manage.chargelyapp.dev\/sso\/jwt\/login?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJyd1RBVnZGM2lIS3Z3blY4bEFqZjIwSzRVbk5sZjJFZyIsImlhdCI6MTQyOTU3NTk3NiwiYXVkIjoiLSIsImN1c3RfZW1haWwiOiJjaGFyZ2VseV8xMzM0NTAyNjUzQG1haWxpbmF0b3IuY29tIn0.QdMDi1odd3ALH05oQpQr5zY5NLr1qRku0uIUevHv1uQ&public_key=Ng2t1S0khsz8uaRpa4yqmAu874IyuL9N&return_to=&login_url=http%3A%2F%2Fchargely-customer.dev%2Flogin.php&logout_url=http%3A%2F%2Fchargely-customer.dev%2Flogout.php"
    }
}

Note

IMPORTANT: Always perform your usual authentication and authorization checks before returning a successful response.

Returning a successful response to non logged-in users may result in unauthorized access to the Chargely billing portal of your customers.

Parameters

The table below describes the parameters that should be returned in the JSON response.

Parameter Required Description
status Yes This should be success if the request was successful, or error if unsuccessful.
data.jwt Yes The JWT token used for SSO. (read more)
data.sso_login_url Yes A fully formed URL for SSO logins. (read more)

Failure response

This response should be sent if the user is not logged in or if there was some other problem processing the request.

HTTP headers

HTTP/1.1 401 Unauthorized
Content-Type: application/json

You could also send HTTP/1.1 403 Forbidden if that is your preference.

HTTP body (JSON)

{
    "status": "error",
    "message": "The user is unauthorized"
}

Parameters

The table below describes the parameters that should be returned in the JSON response.

Parameter Required Description
status Yes This should be error to signify the request was unsuccessful.
message Yes Reason for the error.