> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Claves de API y autenticación

> Crea una clave de API y envíala en la cabecera X-API-Key desde la API REST, la CLI o el servidor MCP. Los clientes MCP también pueden conectarse con OAuth (PKCE).

## Autenticación con clave de API

Las solicitudes a la API REST usan una clave de API enviada en la cabecera `X-API-Key`. Los clientes MCP pueden usar una clave de API o OAuth con PKCE aprobado por el usuario.

Los agentes de IA pueden empezar con [Auth.md](https://so-me.studio/auth.md), que cubre el descubrimiento de OAuth, el registro de clientes, el consentimiento del usuario, la renovación de tokens y el aprovisionamiento de claves de API para la CLI.

```bash theme={null}
X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

## Generar una clave de API

**1. Inicia sesión en tu panel**

Ve a [Social media studio](https://so-me.studio/es) e inicia sesión.

**2. Abre los ajustes de la API**

Ve a **Configuración** > pestaña **API**.

**3. Crea una clave nueva**

Haz clic en **Nueva clave de API** y ponle un nombre.

**4. Elige el acceso**

Deja **Acceso completo**, o selecciona **Restringido** y establece cada recurso en **Sin acceso**, **Lectura** o **Lectura y escritura**. Consulta [Scopes](#scopes).

**5. Copia la clave**

Haz clic en **Crear** y copia la clave.

> [!WARNING]
>
> La clave completa se muestra una sola vez. Guárdala de forma segura. Si la pierdes, revoca la clave y crea una nueva.

## Quién puede crear claves

Solo los **propietarios** del espacio de trabajo pueden crear, listar y revocar claves de API. Una clave actúa en nombre del espacio de trabajo en el que se creó, limitada a los datos de ese espacio de trabajo. Si un propietario se va o cambia su acceso, revoca y vuelve a emitir las claves que creó.

## Scopes

Una clave tiene **acceso completo** salvo que le asignes permisos (scopes) al crearla. Todas las claves creadas antes de que existieran los scopes conservan el acceso completo.

Una clave con scopes solo puede llamar a los endpoints que sus scopes cubren. Cualquier otro endpoint devuelve `403 Forbidden` con el scope que falta en el mensaje.

* Un endpoint `GET` necesita `<resource>:read`.
* Un endpoint `POST`, `PUT`, `PATCH` o `DELETE` necesita `<resource>:write`.
* `<resource>:write` incluye `<resource>:read`.

| Recurso | Scopes | Endpoints |
| - | - | - |
| `accounts` | `accounts:read`, `accounts:write` | `/v1/accounts` |
| `posts` | `posts:read`, `posts:write` | `/v1/posts`, `/v1/drafts`, `/v1/approvals` |
| `media` | `media:read`, `media:write` | `/v1/media` |
| `analytics` | `analytics:read` | `/v1/analytics` |
| `inbox` | `inbox:read`, `inbox:write` | `/v1/inbox` |
| `ai` | `ai:read`, `ai:write` | `/v1/ai` |
| `biolinks` | `biolinks:read`, `biolinks:write` | `/v1/biolinks` |
| `teams` | `teams:read`, `teams:write` | `/v1/teams` |
| `settings` | `settings:read`, `settings:write` | `/v1/settings` (consulta las excepciones más abajo) |
| `webhooks` | `webhooks:read`, `webhooks:write` | `/v1/webhooks` |
| `support` | `support:read`, `support:write` | `/v1/support` |
| `templates` | `templates:read` | `/v1/templates` |
| `whatsapp` | `whatsapp:read`, `whatsapp:write` | `/v1/whatsapp` |

Excepciones:

* `POST /v1/media/validate` solo necesita `media:read`, porque no modifica nada.
* `POST /v1/templates/{id}/render` solo necesita `templates:read`.
* Estos endpoints necesitan una clave con acceso completo: `PATCH /v1/settings/profile`, todo `/v1/settings/api-keys` y todo `/v1/settings/tenants`. Una clave con scopes no puede crear una clave nueva ni acceder a otros espacios de trabajo.
* El servidor MCP no acepta claves con scopes. Usa una clave con acceso completo o conéctate con OAuth.
* `teams:write` no puede invitar ni promover a propietarios. Solo una clave con acceso completo puede conceder el rol `owner`.
* Una clave con scopes solo puede suscribirse, listar y reintentar los eventos de webhook que puede leer. Por ejemplo, los eventos de `inbox` necesitan `inbox:read` y los eventos de `post`, `draft` y `approval` necesitan `posts:read`. Los eventos `knowledge`, `organization`, `account`, `auth`, `api_key`, `integration`, `subscription`, `referral`, `mcp` y `quota` necesitan una clave con acceso completo.

Para crear una clave con scopes mediante la API, envía `scopes` a `POST /v1/settings/api-keys` con una clave de acceso completo:

```bash theme={null}
curl https://api.so-me.studio/v1/settings/api-keys \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Zapier", "scopes": ["accounts:read", "posts:write", "media:write"]}'
```

Omite `scopes` para obtener una clave con acceso completo. No puedes cambiar los scopes de una clave. Revócala y crea una nueva.

## Usar tu clave de API

### API REST

Pasa la clave en la cabecera `X-API-Key`:

```bash theme={null}
curl https://api.so-me.studio/v1/posts \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

### Servidor MCP

El servidor MCP usa la misma clave de API. Solo acepta claves con acceso completo. Pasa la clave en la cabecera `X-API-Key` de tu configuración de MCP:

```json theme={null}
{
  "mcpServers": {
    "so-me-studio": {
      "url": "https://api.so-me.studio/mcp",
      "headers": {
        "X-API-Key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Requisitos del plan

El acceso a la API REST, la CLI y MCP está disponible en los planes **Standard**, **Advanced** y **Lifetime**. El plan **Lite** no incluye acceso a la API, la CLI ni MCP.

| Plan | Acceso a la API |
| - | - |
| Lite | No |
| Standard | Sí |
| Advanced | Sí |
| Lifetime | Sí |

Para ver todos los detalles de los planes, consulta la [descripción general de facturación](/es/billing/overview.md).

## Límites de frecuencia

Las solicitudes a la API tienen un límite de frecuencia por espacio de trabajo, y el límite exacto depende de tu plan. Cuando lo superas, recibes una respuesta `429 Too Many Requests`: espera a que se reinicie la ventana y vuelve a intentarlo.

Las llamadas a herramientas MCP también consumen créditos según tu plan. Consulta tu uso en **Configuración** > **API**, y revisa [Créditos de IA](/es/get-started/ai-credits.md) para saber cómo funcionan los créditos.

> [!NOTE]
>
> Los planes superiores tienen límites de frecuencia más altos y mayores cuotas mensuales de uso de la API. Consulta la [descripción general de facturación](/es/billing/overview.md) para ver los límites que se aplican a tu plan.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.