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

# Autenticación

> Guía completa sobre autenticación con la API de NotMeta

## Métodos de autenticación

NotMeta utiliza autenticación basada en tokens JWT (JSON Web Tokens) para garantizar la seguridad de las comunicaciones con la API.

## Tipos de tokens

### Token de API

El token de API es el método principal de autenticación para aplicaciones:

* **Duración**: Configurable (1 día a 1 año)
* **Permisos**: Granular por funcionalidad
* **Uso**: Recomendado para integraciones
* **Renovación**: Manual

### Token de sesión

Token temporal para sesiones de usuario:

* **Duración**: 24 horas
* **Permisos**: Basados en el usuario
* **Uso**: Interfaz web y aplicaciones móviles
* **Renovación**: Automática

## Generar token de API

### Desde el panel web

1. Inicia sesión en NotMeta
2. Ve a "Configuración" > "API"
3. Haz clic en "Generar nuevo token"
4. Configura los permisos necesarios
5. Copia y guarda el token de forma segura

### Desde la API

```bash theme={null}
curl -X POST "https://api.notmeta.com/v1/auth/tokens" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi aplicación",
    "permissions": ["messages:read", "messages:write"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'
```

## Uso del token

### Header de autorización

Incluye el token en el header `Authorization`:

```bash theme={null}
curl -X GET "https://api.notmeta.com/v1/conversations" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### En diferentes lenguajes

#### JavaScript

```javascript theme={null}
const response = await fetch('https://api.notmeta.com/v1/conversations', {
  headers: {
    'Authorization': `Bearer ${process.env.NOTMETA_API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});
```

#### Python

```python theme={null}
import requests

headers = {
    'Authorization': f'Bearer {api_token}',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.notmeta.com/v1/conversations', headers=headers)
```

#### PHP

```php theme={null}
$headers = [
    'Authorization: Bearer ' . $api_token,
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.notmeta.com/v1/conversations');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
```

## Permisos y scopes

### Conversaciones

* `conversations:read` - Leer conversaciones
* `conversations:write` - Crear y modificar conversaciones
* `conversations:delete` - Eliminar conversaciones

### Mensajes

* `messages:read` - Leer mensajes
* `messages:write` - Enviar mensajes
* `messages:delete` - Eliminar mensajes

### Usuarios

* `users:read` - Leer información de usuarios
* `users:write` - Crear y modificar usuarios
* `users:delete` - Eliminar usuarios

### Reportes

* `reports:read` - Acceder a reportes y métricas

### Webhooks

* `webhooks:read` - Leer configuración de webhooks
* `webhooks:write` - Crear y modificar webhooks
* `webhooks:delete` - Eliminar webhooks

### Configuración

* `config:read` - Leer configuración
* `config:write` - Modificar configuración

## Verificación de permisos

### Verificar token

```bash theme={null}
curl -X GET "https://api.notmeta.com/v1/auth/verify" \
  -H "Authorization: Bearer TU_TOKEN"
```

Respuesta:

```json theme={null}
{
  "valid": true,
  "token_type": "api",
  "permissions": ["conversations:read", "messages:write"],
  "expires_at": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-01T00:00:00Z"
}
```

### Verificar permisos específicos

```javascript theme={null}
async function hasPermission(token, permission) {
  const response = await fetch('https://api.notmeta.com/v1/auth/verify', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  const data = await response.json();
  return data.permissions.includes(permission);
}

// Uso
const canSendMessages = await hasPermission(token, 'messages:write');
```

## Renovación de tokens

### Verificar expiración

```javascript theme={null}
function isTokenExpired(token) {
  try {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return payload.exp * 1000 < Date.now();
  } catch (error) {
    return true;
  }
}
```

### Renovar token

```bash theme={null}
curl -X POST "https://api.notmeta.com/v1/auth/refresh" \
  -H "Authorization: Bearer TOKEN_ACTUAL" \
  -H "Content-Type: application/json"
```

## Autenticación OAuth (Futuro)

### Flujo de autorización

```mermaid theme={null}
sequenceDiagram
    participant App as Tu Aplicación
    participant NotMeta as NotMeta API
    participant User as Usuario
    
    App->>User: Redirige a NotMeta
    User->>NotMeta: Autoriza la aplicación
    NotMeta->>App: Código de autorización
    App->>NotMeta: Intercambia código por token
    NotMeta->>App: Token de acceso
```

### Configuración OAuth

```javascript theme={null}
const oauthUrl = `https://api.notmeta.com/oauth/authorize?` +
  `client_id=${CLIENT_ID}&` +
  `redirect_uri=${REDIRECT_URI}&` +
  `scope=${SCOPES}&` +
  `response_type=code&` +
  `state=${RANDOM_STATE}`;
```

## Mejores prácticas de seguridad

### Almacenamiento seguro

```javascript theme={null}
// ❌ Incorrecto - Token en código
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

// ✅ Correcto - Token en variables de entorno
const token = process.env.NOTMETA_API_TOKEN;
```

### Rotación de tokens

```javascript theme={null}
class TokenManager {
  constructor() {
    this.token = null;
    this.refreshToken = null;
    this.expiresAt = null;
  }
  
  async getValidToken() {
    if (!this.token || this.isExpired()) {
      await this.refreshToken();
    }
    return this.token;
  }
  
  isExpired() {
    return this.expiresAt && Date.now() >= this.expiresAt;
  }
  
  async refreshToken() {
    // Implementar lógica de renovación
  }
}
```

### Manejo de errores de autenticación

```javascript theme={null}
async function makeAuthenticatedRequest(url, options = {}) {
  try {
    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${await tokenManager.getValidToken()}`
      }
    });
    
    if (response.status === 401) {
      // Token inválido o expirado
      await tokenManager.refreshToken();
      // Reintentar con nuevo token
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          'Authorization': `Bearer ${await tokenManager.getValidToken()}`
        }
      });
    }
    
    return response;
  } catch (error) {
    console.error('Error de autenticación:', error);
    throw error;
  }
}
```

## Solución de problemas

### Error 401: Unauthorized

* Verifica que el token sea correcto
* Confirma que el token no haya expirado
* Revisa los permisos del token

### Error 403: Forbidden

* Verifica que el token tenga los permisos necesarios
* Confirma que la acción esté permitida para tu rol

### Token expirado

* Implementa renovación automática
* Maneja graciosamente la expiración
* Considera usar tokens de larga duración para aplicaciones

## Recursos adicionales

<Card title="Configuración inicial" icon="gear" href="/developers/setup">
  Configura tu entorno de desarrollo
</Card>

<Card title="Webhooks" icon="webhook" href="/developers/webhooks">
  Configura notificaciones en tiempo real
</Card>