Autenticación

Métodos de autenticación

Existen 2 formas de identificar a un usuario en la API:

  • Utilizando un API key. Este es el método preferido por ser más sencillo.
  • Mediante un token de autenticación. El token es temporal y se obtiene haciendo un llamado a /login indicando nombre de usuario y contraseña.

ATENCION: El API key no debe ser utilizado NUNCA desde el lado del cliente, es decir desde el navegador, mediante javascript. Está diseñado para ser utlizado únicamente desde el lado servidor. Para realizar integraciones desde el navegador utilizando javascript debe realizarse un login solicitando el usuario y contraseña. Incluir el API key en el código javascript es muy inseguro ya que es visible fácilmente por cualquiera que acceda al sitio web.

Autenticación mediante API key

La forma preferida y mas sencilla de utilizar la API es mediante un API key. El API key se obitene desde la sección Ajustes de la aplicación, ingresando al usuario del cuál queremos obtener su API key, en donde encontraremos este botón:

Obtener API Key

El API key tiene los mismos permisos de acceso que el usuario al que pertenece.

Es recomendable crear un usuario dedicado para cada integración que realicemos. Esto nos dará mayor flexibilidad a futuro para modificar permisos o revocar el acceso de cada integración en forma independiente.

Uso del API key

Para realizar llamados a la API utilizando el API key debemos incluir el siguiente encabezado HTTP en cada pedido que realicemos:

Authorization: Bearer API_KEY

Ejemplo:

$lists = file_get_contents(
    'https://apitest.myperfit.com/v2/micuenta/lists',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => 'Authorization: Bearer micuenta-YVhgyuUKUbTXyUwQccYDKAlCsEMI0qgb'
    ]])
);

// No utlices API keys desde javascript!

Si el API key utilizado no tiene acceso al recurso solicitado, recibieremos un error 403 Forbidden. Si el API key es inválido, el error que veremos es 401 Unauthorized

Revocar acceso a un API key

Es posible que en algún momento queramos impedir que un API key siga accediendo a nuestra cuenta, en ese caso podemos revocar el API key haciendo click en el botón:

Revocar API Key

Esta acción no puede revertirse, luego de revocar un API key será necesario reconfigurar cualquier integración que lo estuviese usando.

Todos los intentos de uso del API key revocado serán bloqueado de inmediato. Se deberá generar un nuevo API key haciendo click en Obtener API key, como se indicó arriba.

Autenticación mediante token

Este es el método de autenticación preferido para el uso de la API desde el navegador. El token es temporal, luego de un tiempo de inactividad expira, y se deberá obtener uno nuevo. Por ejemplo, la aplicación web de Perfit utiliza este método de autenticación, generando un token a partir del usuario y contraseña ingresados en el login.

Cómo obtener un token

Para obtener un token debes hacer un POST a login, enviando el nombre de usuario y contraseña. Hay dos formas de identificar al usuario:

  • A través de su email
  • A través de su usuario y cuenta, unidos por una arroba (usuario@cuenta)

La conexión con el API es una conexión segura (SSL). Tus datos están resguardados.

En el primer caso, si existen varios usuarios de distintas cuentas con el mismo email, se deberá especificar también la cuenta en la cuál se desea trabajar.

A continuación, vemos ejemplos de cada tipo de autenticación:

Con email

$login = file_get_contents(
    'https://api.myperfit.com/v2/login',
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => 'Content-Type: application/x-www-form-urlencoded',
        'content' => http_build_query([
            'user' => 'juan@gmail.com',
            'password' => '123456'
        ])
    ]])
);

$access_token = json_decode($login)->data->token;
$.ajax({
    type: 'POST',
    url: 'https://api.myperfit.com/v2/login',
    data: {
        user: 'juan@gmail.com',
        password: '123456'
    },
    success: function (response) {
        var access_token = response.data.token;
    }
});

Con email y cuenta

$login = file_get_contents(
    'https://api.myperfit.com/v2/login',
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => 'Content-Type: application/x-www-form-urlencoded',
        'content' => http_build_query([
            'user' => 'juan@gmail.com',
            'account' => 'cuenta',
            'password' => '123456'
        ])
    ]])
);

$access_token = json_decode($login)->data->token;
$.ajax({
    type: 'POST',
    url: 'https://api.myperfit.com/v2/login',
    data: {
        user: 'juan@gmail.com',
        account: 'cuenta',
        password: '123456'
    },
    success: function (response) {
        var access_token = response.data.token;
    }
});

Con usuario@cuenta

$login = file_get_contents(
    'https://api.myperfit.com/v2/login',
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => 'Content-Type: application/x-www-form-urlencoded',
        'content' => http_build_query([
            'account' => 'usuario@cuenta',
            'password' => '123456'
        ])
    ]])
);

$access_token = json_decode($login)->data->token;
$.ajax({
    type: 'POST',
    url: 'https://api.myperfit.com/v2/login',
    data: {
        user: 'miusuario@micuenta',
        password: '123456'
    },
    success: function (response) {
        var access_token = response.data.token;
    }
});

Token y datos de usuario

Al loguearse con éxito, el sistema devuelve una respuesta con status 201 Created y un contenido como el siguiente:

{
    "href": "/login",
    "success": true,
    "data": {
        "token": "Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s",
        "user": "miusuario",
        "userType": "ACCOUNT",
        "account": "micuenta",
        "tokenExpiration": 28800,
        "acl": {
            "cuenta1": [
                "contacts:list",
                "contacts:create",
                "contacts:delete",
                "contacts:update",
                ...
            ]
        },
        "details": { ... }
    }
}

En data tendremos la información de la sesión iniciada. El token nos servirá para realizar llamados a la API en nombre del usuario user. En account encontraremos la cuenta principal (a la cual pertenece el usuario), y en acl un listado de cuentas a las que tiene acceso (en caso de ser usuario de una cuenta agencia, puede tener acceso a varias cuentas), cada una con un listado de permisos que determinan las acciones que puede realizar en la API. Si intentamos realizar una acción para la cuál no tenemos permiso, recibiremos un error 403 Forbidden.

El token expira luego de que no es utilizado por el lapso especificado en tokenExpiration, en segundos. Cuando el token expira, cualquier pedido que se realice utilizando ese token devolverá un error 401 Unauthorized. Será necesario entonces volver a realizar la autenticación.

Mensajes de error

Luego del intento de login, además de los errores estándar, podemos recibir los siguientes errores específicos:

Status Type Descripción
401 UNAUTHORIZED La contraseña no es válida.
401 PASSWORD_EXPIRED La contraseña ha expirado.
409 ACCOUNT_REQUIRED El email que enviamos está asociado a varias cuentas, y la cuenta no ha sido especificada.
503 SERVICE_UNAVAILABLE Para evitar abusos, el servidor está limitando el acceso debido a un exceso en la cantidad de intentos en un determinado tiempo.

Error por cuenta no especificada

Cuando ingresamos utilizando un email, si ese email está asociado a varias cuentas, debemos especificar a cual queremos acceder utilizando el parámetro account. En caso de no hacerlo, el API nos devolverá un error 409 Conflict, con un listado de las cuentas disponibles para ese email. El listado es proporcionado siempre y cuando la contraseña sea correcta para alguna de las cuentas.

{
    "href": "/login",
    "success": false,
    "error": {
        "status": 409,
        "type": "ACCOUNT_REQUIRED",
        "userMessage": "Se debe indicar el nombre de la cuenta"
    },
    "data": [
        "cuenta1",
        "cuenta2",
        "cuenta3"
    ]
}

Contraseña expirada

Si la contraseña de nuestro usuario ha expirado o debe ser renovada, recibiremos un error 401 Unauthorized con el siguiente contenido:

{
    "href": "/login",
    "success": false,
    "error": {
        "status": 401,
        "type": "PASSWORD_EXPIRED",
        "userMessage": "La contraseña debe ser renovada"
    }
}

En este caso, debe volverse a realizar el login, indicando también la nueva contraseña en el campo newPassword.