API Reference guide

HTTP API introduction

  • The API is a standard HTTP server which supports only the method GET and POST.
  • The URL of the API server is https://api.remauth.com.
  • The HTTP errors are only about request failures e.g.

    • 403: Forbidden access
    • 404: Unknown endpoint
    • 405: Wrong HTTP method
    • ...
  • Any successful HTTP requests returns a JSON object as in the following examples:

// Example of nominal response where code="200"
{code: "200", msg: "OK", data: "1.0.0"}
// Example of error response
{code:"601", msg:"Invalid parameter. See data for details", data:"key"}

Do not hesitate to play with each endpoint using the TRY THIS ENDPOINT buttons below. You can get service credentials (key, secret) from your Customer Center account.

Event notification

Some events are completely out of sync of the main API requests because they are triggered by some human interaction in a remote context (e.g. mailbox, cellphone, mobile application).

For those kinds of events, customer services are notified using web socket and callback events.

Web socket

To provide web users with a simple user experience, it is convenient to push events in real time directly on the client side of the services. This is useful to react on end user action initiated from any authentication source defined by its unique authentication ID (uaid) as returned by the /authenticate endpoint.

It is the reason why RemAuth sends real time web socket messages based on socket.io technologies. On service client side, a web socket client is required to listen to these messages. See the example below to load and to intialize the socket.io client and to listen to authentication status change whatever the status.


                    

Callback events

In order to be notified on server on server side, customer systems must define a simple HTTP server to receive callback events. The URL of this server must be entered in the Customer Center SERVICES section. For example such an URL could be https://myservice.com/remauth_callback.

When defined, RemAuth will use this URL with parameters depending on the authentication process applied according to the current use case according to the following decision tree:

When a user authenticates

Using the above URL, the complete request would be as follows,

https://myservice.com/remauth_callback?authenticated=b83ee873a9b44f2083c130db24dfbe91

where the authenticated parameter is valued by an authentication ID.

When a user authenticates for the first time with RemAuth

This is the same as the previous example but with the registricated parameter.

https://myservice.com/remauth_callback?registricated=b83ee873a9b44f2083c130db24dfbe91

When a user subscribes to an existing system with RemAuth

This is the same as the previous example but with the subscribed parameter.

https://myservice.com/remauth_callback?subscribed=b83ee873a9b44f2083c130db24dfbe91

HTTP endpoints