Claves de API y autenticación

Cada llamada REST y cada sesión MCP se autentican con una clave de API que creas en la aplicación. Una clave actúa en tu nombre, limitada a los permisos que le concedas. Hay un solo tipo de clave y un solo header, tanto para la API REST como para el servidor MCP.

app.stickyprompts.com/settings#api 1 Crea una clave 2 El único header que necesitas 3 Renombra, ajusta o elimina

Crea una clave

1. Abre Settings > API keys

   Ve a Settings y selecciona API keys.

2. Genera una clave

   Selecciona Generate key. Ponle un nombre que indique dónde se va a usar (por ejemplo, Northwind CRM sync) y marca los permisos que necesita (consulta la referencia de permisos).

3. Copia la clave

   La clave completa se muestra una única vez, justo después de crearla. No se puede recuperar más tarde, ni tú ni StickyPrompts. Guárdala directamente en tu gestor de secretos.

Las claves solo las puede crear un usuario que haya iniciado sesión en la aplicación. Los endpoints de gestión de claves no se pueden llamar con una clave de API, así que una clave nunca puede crear, listar ni modificar claves.

Formato de la clave

STICKY-API-<64 characters>

• El prefijo es siempre STICKY-API-, seguido de 64 caracteres aleatorios. La clave completa tiene 75 caracteres.
• La parte aleatoria usa dígitos, consonantes (sin vocales), - y _.
• StickyPrompts solo guarda un hash del secreto, además de sus primeros 16 caracteres para localizarlo. Por eso una clave perdida no se puede volver a mostrar.

Ciclo de vida

Envía la clave

Envía la clave como token Bearer en el header Authorization de cada petición:

Authorization: Bearer STICKY-API-...

El prefijo Bearer STICKY-API- distingue entre mayúsculas y minúsculas y tiene que ser exacto. No hay alternativa mediante query string ni cookies.

curl https://api.stickyprompts.com/api/v1/workspace \
  -H "Authorization: Bearer $STICKY_API_KEY"

import os
import requests

r = requests.get(
    "https://api.stickyprompts.com/api/v1/workspace",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
)
print(r.status_code, r.json())

const res = await fetch("https://api.stickyprompts.com/api/v1/workspace", {
  headers: { Authorization: `Bearer ${process.env.STICKY_API_KEY}` },
});
console.log(res.status, await res.json());

(GET /workspace requiere el permiso organization_get).

Qué puede ver una clave

Una clave actúa como el usuario que la creó. Ve exactamente lo mismo que ese usuario (su espacio de trabajo, sus proyectos y todo lo que se ha compartido con él) y sus permisos restringen después ese acceso. Una clave no se puede limitar a un espacio de trabajo o a un proyecto concretos.

Si tu cuenta deja de estar activa, tus claves dejan de funcionar con ella. Si sales de un espacio de trabajo o pierdes el acceso a un proyecto, tus claves también pierden ese acceso.

Cómo se valida una petición

Cada petición pasa por estas comprobaciones, en este orden. La primera que falla determina la respuesta.

Además, las peticiones procedentes de una región en la que el servicio no está disponible se rechazan con 403 {"error":"access from your region is not supported"}, tanto en REST como en MCP.

El error de permisos indica el permiso que te falta, así que normalmente basta con editar la clave y marcarlo:

{"error": "This api key does not have any of the required permissions. You need at least one of: prompts_get"}

En MCP, el paso 4 funciona de otra manera: cualquier clave válida y activa se conecta, y las herramientas para las que la clave no tiene permiso simplemente no se muestran. Consulta Introducción a MCP.

Rutas que una clave nunca puede usar

Algunas partes de la API están reservadas a una persona que haya iniciado sesión en la aplicación. En ellas, una clave de API recibe 403 sean cuales sean sus permisos:

• Las rutas de cuenta, inicio de sesión y autenticación.
• Las rutas de facturación y suscripción.
• La gestión de claves de API (crear, listar, editar y eliminar claves).
• Las rutas de administración reservadas al personal de StickyPrompts.
• Algunas rutas registradas sin ningún permiso de clave de API, por ejemplo la lectura de un prompt concreto, GET /prompt/:id, y la compartición de agentes (GET /agents/:id/shares y las rutas PATCH /agents/:id/share_with_*). Los agentes se comparten desde la aplicación.

Mantén tus claves seguras

• Solo en el servidor. Guarda las claves en variables de entorno o en un gestor de secretos. Nunca las subas a un repositorio, las escribas en logs ni las pegues en tickets o chats.
• Mínimo privilegio. Marca solo los permisos que usa la integración. Un bot de informes no necesita integration_email_manage. Parte de los conjuntos recomendados.
• Una clave por integración. Ponle a cada clave el nombre del sistema que la usa. Así podrás revocar una integración sin afectar a las demás y ver, por la fecha de último uso, si sigue activa.
• Rótalas. Sustituye las claves con la periodicidad que te convenga, y de inmediato cuando se vaya alguien que tenía acceso o cuando una clave haya podido filtrarse. Crea primero la clave nueva, haz el cambio y después elimina la antigua.
• Recuerda a quién representa la clave. Una clave actúa en tu nombre. Para una integración compartida, plantéate crear la clave desde una cuenta cuyo acceso coincida con lo que debe ver la integración.

Páginas relacionadas