Ir al contenido
Quiet Social

Autenticación

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

La API autentica una aplicación, no a una persona. Cada aplicación cliente recibe un identificador público y un secreto, que presenta mediante autenticación HTTP Basic en cada petición.

Obtener credenciales

Un cliente de API pertenece a un espacio de trabajo y, si procede, a una sola marca de ese espacio. Lleva una lista de permisos que decide lo que puede hacer.

Las claves se crean en el panel, menú Clés API (Claves API), abierto a los administradores y al propietario del espacio: Créer une clé API (Crear una clave API), luego un Nom (Nombre), la Marque (Marca) — o «Tout l'espace de travail» (Todo el espacio de trabajo) — y los Droits (Permisos). El recorrido completo está en la guía.

  • El identificador empieza por qsc_, el secreto por qss_.
  • El secreto se muestra una sola vez, al crearla. Solo se conserva su huella: no se puede volver a leer, y perderlo obliga a crear una clave nueva.
  • Guárdalo en un gestor de secretos o en una variable de entorno, nunca en el código fuente.
  • Una clave revocada desde el panel pierde el acceso desde su siguiente petición, y no se reactiva.

Presentar las credenciales

El identificador es el nombre de usuario, el secreto es la contraseña:

curl https://quietsocial.dev/api/v1/me \
  -u "qsc_a1b2c3d4e5f6g7h8i9j0k1l2:qss_…"

Lo que equivale a enviar la cabecera:

Authorization: Basic base64(identificador:secreto)

Las mismas credenciales también se aceptan como token portador, en claro, separadas por dos puntos — la forma que saben poner la mayoría de los clientes del servidor MCP:

Authorization: Bearer qsc_a1b2c3d4e5f6g7h8i9j0k1l2:qss_…

La verificación y los rechazos son los mismos que con Basic.

Cualquier cliente HTTP sabe generar la cabecera Basic. En Laravel:

use Illuminate\Support\Facades\Http;

$response = Http::baseUrl('https://quietsocial.dev/api/v1')
    ->withBasicAuth(config('services.quiet_social.client_id'), config('services.quiet_social.client_secret'))
    ->acceptJson()
    ->get('/me');

Ninguna ruta de la API es pública. Una petición sin credenciales válidas recibe 401:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid credentials."
  }
}

Un identificador desconocido, un secreto erróneo y un cliente revocado reciben el mismo código y el mismo mensaje, y tardan el mismo tiempo: la respuesta no permite adivinar qué identificadores existen. Cuando la cabecera falta, o no es ni Basic decodificable ni un token portador identificador:secreto, el mensaje pasa a ser « Send your client ID and secret with HTTP Basic authentication, or as a Bearer token "client_id:secret". » (Proporciona tu identificador y tu secreto mediante autenticación HTTP Basic, o como token portador); el código sigue siendo unauthenticated.

GET /me

Indica quién es el cliente que llama. Es la única ruta que no exige ningún permiso.

curl https://quietsocial.dev/api/v1/me \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET"
{
  "data": {
    "client": {
      "id": "qsc_a1b2c3d4e5f6g7h8i9j0k1l2",
      "name": "Site vitrine",
      "abilities": [
        "destinations:read",
        "publications:read",
        "publications:create",
        "media:create"
      ]
    },
    "workspace": {
      "name": "Fabrique du Nord"
    },
    "brand": {
      "id": "brd_01k4b8x2q9r7f3m5t6v8w0y2z4",
      "name": "Fabrique du Nord",
      "timezone": "Europe/Paris"
    }
  }
}
  • client.abilities lista los permisos concedidos. Compárala desde el arranque con lo que necesita tu integración.
  • brand vale null cuando el cliente cubre todo el espacio de trabajo. Es la comprobación que debes hacer para saber si tus escrituras deben llevar brand_id (consulta Permisos).
  • El espacio de trabajo solo devuelve su nombre: no tiene identificador público, nada en la API se designa por un espacio.

Códigos: 200, 401, 429.

Lo que registra la API

Cada llamada autenticada actualiza la fecha y la dirección IP de último uso del cliente, y cuenta una petición en el consumo del espacio de trabajo. Estas escrituras se producen después de la respuesta: no la retrasan, y si fallan, la llamada no falla.