{% extends "templates/base.html" %} {% block head %} {% endblock %} {% block navbar %}{{ select_navbar('API') }}{% endblock %} {% block body %}

{% trans %}API Documentation{% endtrans %}

{% trans %} This documentation provides the necessary information for {{ APP_NAME }} integration on websites. It is supposed that people reading these docs has basic knowledge about HTTP GET and POST calls and JSON.{% endtrans %}

{% trans %}Table of Contents{% endtrans %}

  1. {% trans %}Overview{% endtrans %}
  2. {% trans %}Summary{% endtrans %}
  3. {% trans %}Registering Sites{% endtrans %}

{% trans %}Overview{% endtrans %}

{% trans %} The sequence diagram on right shows the overview schema of authentication. It contains the following steps:{% endtrans %}

  1. {% trans %} After registering your site, you can make a HTTP Post call to {{ APP_NAME }} with user email or id;{% endtrans %}
  2. {% trans %} {{ APP_NAME }} send an email to user containing a secure login link;{% endtrans %}
  3. {% trans %} User clicks on login link;{% endtrans %}
  4. {% trans %} {{ APP_NAME }} send a HTTP Get call to your site so you know she logged in;{% endtrans %}
  5. {% trans %} Your site send a HTTP Get call to {{ APP_NAME }} asking for user id and email;{% endtrans %}
  6. {% trans %} After receiving user data, you log the user in and show your welcome page;{% endtrans %}

{% trans %}Each step, including parameters and response formats, will be explained in detail on following sections.{% endtrans %}

{% trans %}Summary shows all the available REST api. The return format is JSON.{% endtrans %}

Authentication Sequence Diagram

{% trans %}Table 1 - Summary{% endtrans %}

{% set API_BASE_URL ='https://'+ APP_HOST +'/rest' %}
{% trans %}Call{% endtrans %} {% trans %}Parameters{% endtrans %} {% trans %}Return{% endtrans %} {% trans %}Description{% endtrans %}
{{ API_BASE_URL }}/login {% trans %}

Required

app_id (String) - the registered domain id;
token (String) - the registered domain token;
hook (String) - the address on your website which {{ APP_NAME }} will make a post call indicating user has logged in.

Optional

email (String) - user's email. Ignored if id is present;
user_id (String) - user's id on {{ APP_NAME }};
lang (String) - The language {{ APP_NAME }} must use on email. Available values: en_US (English) and pt_BR (Brazilian Portuguese). Default: en_US.{% endtrans %}
{% trans %}JSON containing the ticket of the login call. Ex: {ticket:"123456"}.{% endtrans %} {% trans %}This call will send user an email containing the login link. One of id or email must be sent. If the two are specified, id will be used to identify the user instead of email. Returns a ticket so your website can certify that it has done this call.{% endtrans %}
Your hook {% trans %}

Required

ticket (String) - the ticket sent login call;
{% endtrans %}
{% trans %} Your site need to sent a 200 HTTP status code. Any message sent is ignored {% endtrans %} {% trans %}After user click on link sent by email, {{ APP_NAME }} will make a Post call on the hook defined on login phase containing the ticket number. This ticket can be used to retrieve user's detail from {{ APP_NAME }}.{% endtrans %}
{{ API_BASE_URL }}/detail {% trans %}

Required

token (String) - the registered domain token;
ticket (String) - the code sent to your hook url.
{% endtrans %}
{% trans %}JSON containing user's details. Ex: {id:"654321",email:"foo@bar.com"}.{% endtrans %} {% trans %}This call returns the user's details that can save in your site. The id of a user will never change, so you can use it as a strong reference. After this call, you can save cookies on user's browser to keep she logged.{% endtrans %}

{% trans %}Registering Sites{% endtrans %}

Prior to make API calls, you need to register the site which you intend to use {{ APP_NAME }}. After the registration, a token will be assigned to your site and it will be used on every call.

{% endblock %}