Autenticación

Claves de API para tu propia empresa y OAuth con PKCE para plataformas que publican en nombre de muchas empresas.

Todas las peticiones a /v1 y al MCP llevan la cabecera Authorization: Bearer <token>. Puede ser una clave de API (rk_live_…, rk_test_…) o un access token de OAuth (ro_at_…): funcionan igual.

Claves de API

Se crean en Mi empresa → Integraciones (owner o admin). La clave se muestra una sola vez; Remolom solo guarda su hash.

bash
curl https://remolom.com/api/v1/branches -H "Authorization: Bearer rk_test_…"

Permisos (scopes)

ScopePermite
events:readLeer eventos y sedes (GET /v1/events, GET /v1/branches)
events:writeCrear, editar, hacer upsert, cancelar eventos y subir pósters
tickets:readVer entradas, compradores y estadísticas de venta
webhooks:manageGestionar webhooks por API (/v1/webhooks)

En el panel, toda clave lleva events:read; las casillas añaden events:write y tickets:read. Los webhooks se gestionan desde el panel, o por API con una app OAuth que pida webhooks:manage. Sin el scope necesario la respuesta es 403.

OAuth para plataformas

Si tu software (ticketing, CMS, agenda cultural…) publica en nombre de muchas empresas, no pidas claves: registra una app OAuth y deja que cada empresa te dé permiso con un clic. Flujo authorization code con PKCE (S256 obligatorio). Cada empresa puede revocar el acceso cuando quiera.

1. Registra la app

En Mis apps OAuth crea la app con nombre, web (https), logo opcional y las redirect_uri exactas (https, o http://localhost / 127.0.0.1 para desarrollo; de 1 a 10). Recibes:

La app nace pendiente: hasta que Remolom la apruebe solo puede conectarse a empresas donde tú eres owner o admin. Perfecto para probar.

Las mismas rutas de la página (con tu sesión de Remolom):

RutaPara qué
GET /api/oauth/clientsTus apps ({ clients })
POST /api/oauth/clientsCrear { name, website, logoUrl?, redirectUris } → { client, clientSecret }
PATCH /api/oauth/clients/:idEditar nombre, web, logo o redirectUris (solo lo que mandes) → { client }
POST /api/oauth/clients/:id/rotate-secretNuevo client_secret, visible una vez → { client, clientSecret }. El anterior deja de valer al momento; los tokens ya emitidos siguen funcionando

2. Manda al usuario a autorizar

Genera un code_verifier aleatorio (43–128 caracteres), su code_challenge = base64url(sha256(verifier)) y un state. Guarda los dos en la sesión de tu usuario.

text
https://remolom.com/api/oauth/authorize
  ?response_type=code
  &client_id=ro_ci_…
  &redirect_uri=https://tu-app.com/callback
  &scope=events:read events:write
  &state=…
  &code_challenge=…
  &code_challenge_method=S256

El usuario ve la pantalla de consentimiento en /oauth/authorize, elige la empresa y autoriza. Remolom vuelve a tu redirect_uri con ?code=ro_ac_…&state=…, o con ?error=access_denied&state=… si cancela. Comprueba siempre que state es el tuyo.

3. Cambia el código por tokens

POST https://remolom.com/api/oauth/token (form-urlencoded o JSON). El código vale 60 segundos y un solo intento; si alguien lo vuelve a usar, se revoca el permiso que emitió.

bash
curl -X POST https://remolom.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=ro_ac_… \
  -d redirect_uri=https://tu-app.com/callback \
  -d code_verifier=$VERIFIER \
  -d client_id=ro_ci_… \
  -d client_secret=ro_cs_…

Respuesta:

json
{ "access_token": "ro_at_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "ro_rt_…", "scope": "events:read events:write" }

El access token dura 1 hora y el refresh token 90 días. El token actúa en nombre de quien autorizó y sobre la empresa que eligió.

4. Renueva el token

bash
curl -X POST https://remolom.com/api/oauth/token \
  -d grant_type=refresh_token -d refresh_token=ro_rt_… \
  -d client_id=ro_ci_… -d client_secret=ro_cs_…

Cada renovación devuelve un refresh token nuevo y el anterior deja de valer. Reusar un refresh token ya usado (o mandar dos renovaciones a la vez) revoca el permiso entero: guarda siempre el último.

5. Revoca

POST /api/oauth/revoke con token, client_id y client_secret (RFC 7009) revoca el permiso completo. Siempre responde 200 {}. La empresa también puede revocarlo en su panel, en Apps conectadas.

Ejemplo completo en Node

js
import { createHash, randomBytes } from 'node:crypto'

const CLIENT_ID = process.env.REMOLOM_CLIENT_ID
const CLIENT_SECRET = process.env.REMOLOM_CLIENT_SECRET
const REDIRECT_URI = 'https://tu-app.com/callback'

// Paso 2: URL de autorización. Guarda verifier y state en la sesión del usuario.
export function authorizeUrl(session) {
  session.verifier = randomBytes(32).toString('base64url')
  session.state = randomBytes(16).toString('base64url')
  const challenge = createHash('sha256').update(session.verifier).digest('base64url')
  const q = new URLSearchParams({
    response_type: 'code', client_id: CLIENT_ID, redirect_uri: REDIRECT_URI,
    scope: 'events:read events:write', state: session.state,
    code_challenge: challenge, code_challenge_method: 'S256',
  })
  return `https://remolom.com/api/oauth/authorize?${q}`
}

// Paso 3: en tu /callback.
export async function callback(session, query) {
  if (query.error) throw new Error(query.error)
  if (query.state !== session.state) throw new Error('state no coincide')
  const res = await fetch('https://remolom.com/api/oauth/token', {
    method: 'POST',
    body: new URLSearchParams({
      grant_type: 'authorization_code', code: query.code, redirect_uri: REDIRECT_URI,
      code_verifier: session.verifier, client_id: CLIENT_ID, client_secret: CLIENT_SECRET,
    }),
  })
  if (!res.ok) throw new Error((await res.json()).error)
  return res.json() // { access_token, refresh_token, expires_in, scope }
}

Ejemplo completo en Python

python
import base64, hashlib, os, secrets, requests
from urllib.parse import urlencode

CLIENT_ID = os.environ["REMOLOM_CLIENT_ID"]
CLIENT_SECRET = os.environ["REMOLOM_CLIENT_SECRET"]
REDIRECT_URI = "https://tu-app.com/callback"

def authorize_url(session: dict) -> str:
    session["verifier"] = secrets.token_urlsafe(32)
    session["state"] = secrets.token_urlsafe(16)
    challenge = base64.urlsafe_b64encode(hashlib.sha256(session["verifier"].encode()).digest()).rstrip(b"=").decode()
    return "https://remolom.com/api/oauth/authorize?" + urlencode({
        "response_type": "code", "client_id": CLIENT_ID, "redirect_uri": REDIRECT_URI,
        "scope": "events:read events:write", "state": session["state"],
        "code_challenge": challenge, "code_challenge_method": "S256",
    })

def callback(session: dict, args: dict) -> dict:
    if "error" in args:
        raise RuntimeError(args["error"])
    if args.get("state") != session["state"]:
        raise RuntimeError("state no coincide")
    r = requests.post("https://remolom.com/api/oauth/token", data={
        "grant_type": "authorization_code", "code": args["code"], "redirect_uri": REDIRECT_URI,
        "code_verifier": session["verifier"], "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET,
    })
    r.raise_for_status()
    return r.json()  # access_token, refresh_token, expires_in, scope

Errores de OAuth