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

# Autenticación

> Como autenticar tu aplicación con la API de Neuracall

## Descripción General

Neuracall utiliza **OAuth2** con **Auth0** para autenticación. Todos los endpoints (excepto `/v1/auth`) requieren un token de acceso valido.

## Flujo de Autenticación

```mermaid theme={null}
sequenceDiagram
    participant App as Tu Aplicación
    participant API as Neuracall API
    participant Auth0 as Auth0

    App->>API: POST /v1/auth (credentials)
    API->>Auth0: Validar credenciales
    Auth0-->>API: Token JWT
    API-->>App: access_token + expires_at
    App->>API: GET /v1/call-analysis (Bearer token)
    API-->>App: Datos
```

## Obtener Credenciales

Para usar la API necesitas:

| Credencial      | Descripción                          |
| --------------- | ------------------------------------ |
| `client_id`     | Identificador único de tu aplicación |
| `client_secret` | Clave secreta (mantener segura)      |

<Note>
  Contacta a [support@neuracall.com](mailto:support@neuracall.com) para solicitar tus credenciales de API.
</Note>

## Obtener Token de Acceso

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.neuracall.com/v1/auth \
    -H "Content-Type: application/json" \
    -d '{
      "client_id": "nc_client_a1b2c3d4e5f6g7h8",
      "client_secret": "nc_secret_x9y8z7w6v5u4t3s2"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.neuracall.com/v1/auth",
      json={
          "client_id": "nc_client_a1b2c3d4e5f6g7h8",
          "client_secret": "nc_secret_x9y8z7w6v5u4t3s2"
      }
  )
  data = response.json()
  token = data["access_token"]
  expires_at = data["expires_at"]
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.neuracall.com/v1/auth", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: "nc_client_a1b2c3d4e5f6g7h8",
      client_secret: "nc_secret_x9y8z7w6v5u4t3s2"
    })
  });

  const { access_token, expires_at } = await response.json();
  ```
</CodeGroup>

### Respuesta

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1735689600,
  "client_id_audience": "https://api.neuracall.com/call-analysis",
  "scope": "read:call-analysis-requests write:call-analysis-request read:call-analysis-audio read:call-analysis-transcription read:prompt-template write:prompt-template read:call-analysis-stats"
}
```

## Usar el Token

Incluye el token en el header `Authorization` de cada solicitud:

```
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.neuracall.com/v1/call-analysis \
    -H "Authorization: Bearer TU_ACCESS_TOKEN"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.neuracall.com/v1/call-analysis",
      headers={"Authorization": f"Bearer {token}"}
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.neuracall.com/v1/call-analysis", {
    headers: { "Authorization": `Bearer ${access_token}` }
  });
  ```
</CodeGroup>

## Scopes (Permisos)

Los tokens incluyen scopes que determinan que operaciónes puede realizar tu aplicación:

| Scope                              | Descripción                       |
| ---------------------------------- | --------------------------------- |
| `read:call-analysis-requests`      | Listar y ver análisis de llamadas |
| `write:call-analysis-request`      | Crear nuevos análisis             |
| `read:call-analysis-audio`         | Descargar archivos de audio       |
| `read:call-analysis-transcription` | Ver transcripciónes               |
| `read:prompt-template`             | Ver modelos de análisis           |
| `write:prompt-template`            | Crear y editar modelos            |
| `read:call-analysis-stats`         | Acceder a estadísticas            |

## Manejo de Expiracion

Los tokens tienen una duración limitada. El campo `expires_at` indica el timestamp Unix de expiración.

<Tip>
  **Recomendacion**: Renueva el token antes de que expire para evitar interrupciones.
</Tip>

```python Python - Renovacion automática theme={null}
import time

class NeuracallClient:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token = None
        self.expires_at = 0

    def get_token(self):
        # Renovar si expira en menos de 5 minutos
        if time.time() > self.expires_at - 300:
            response = requests.post(
                "https://api.neuracall.com/v1/auth",
                json={
                    "client_id": self.client_id,
                    "client_secret": self.client_secret
                }
            )
            data = response.json()
            self.token = data["access_token"]
            self.expires_at = data["expires_at"]
        return self.token
```

## Errores de Autenticación

| Código | Descripción            | Solucion                                     |
| ------ | ---------------------- | -------------------------------------------- |
| 401    | Credenciales invalidas | Verifica client\_id y client\_secret         |
| 401    | Token expirado         | Solicita un nuevo token                      |
| 401    | Token invalido         | Verifica el formato del header Authorization |
| 403    | Scope insuficiente     | Contacta soporte para ampliar permisos       |

### Ejemplo de error

```json theme={null}
{
  "code": "001-001-0001",
  "message": "Invalid credentials"
}
```

## Seguridad

<Warning>
  **Nunca expongas tus credenciales** en código del lado del cliente, repositorios publicos o logs.
</Warning>

### Mejores practicas

1. Almacena credenciales en variables de entorno
2. Usa un gestor de secretos en produccion
3. Rota las credenciales periodicamente
4. Monitorea el uso de la API por actividad sospechosa

```bash Ejemplo con variables de entorno theme={null}
export NEURACALL_CLIENT_ID="nc_client_..."
export NEURACALL_CLIENT_SECRET="nc_secret_..."
```

```python Python theme={null}
import os

client_id = os.environ["NEURACALL_CLIENT_ID"]
client_secret = os.environ["NEURACALL_CLIENT_SECRET"]
```