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.
- Real (
rk_live_…): publica eventos reales, visibles para todo el mundo. - Prueba (
rk_test_…): lo que crea lleva"test": true, no sale en búsquedas, mapa ni perfiles y se borra a los 7 días. Una clave de prueba solo ve sus eventos de prueba, y una real solo los reales; el resto da 404. - La clave actúa en nombre de quien la creó. Si esa persona deja de ser owner o admin, o se suspende su cuenta, la clave deja de valer (401).
- Puedes revocarla cuando quieras desde el mismo panel.
- Máximo de claves activas: 2 en el plan gratis y 10 con Remolom PRO.
curl https://remolom.com/api/v1/branches -H "Authorization: Bearer rk_test_…"Permisos (scopes)
| Scope | Permite |
|---|---|
events:read | Leer eventos y sedes (GET /v1/events, GET /v1/branches) |
events:write | Crear, editar, hacer upsert, cancelar eventos y subir pósters |
tickets:read | Ver entradas, compradores y estadísticas de venta |
webhooks:manage | Gestionar 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:
client_id(ro_ci_…): público.client_secret(ro_cs_…): se ve una sola vez. Guárdalo en tu servidor.
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):
| Ruta | Para qué |
|---|---|
GET /api/oauth/clients | Tus apps ({ clients }) |
POST /api/oauth/clients | Crear { name, website, logoUrl?, redirectUris } → { client, clientSecret } |
PATCH /api/oauth/clients/:id | Editar nombre, web, logo o redirectUris (solo lo que mandes) → { client } |
POST /api/oauth/clients/:id/rotate-secret | Nuevo 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.
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=S256El 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ó.
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:
{ "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
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
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
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, scopeErrores de OAuth
401 { "error": "invalid_client" }:client_idoclient_secretincorrectos. También se aceptan porAuthorization: Basic.400 { "error": "invalid_grant", "error_description": … }: código caducado o usado,redirect_uridistinta,code_verifierque no casa o refresh token no válido.400 { "error": "unsupported_grant_type" }: soloauthorization_codeyrefresh_token.- Con el token: 401 si el permiso se revocó, la app se suspendió o quien autorizó ya no gestiona la empresa; 403 si falta el scope.