Gestión de API keys
Crea, lista, rota y elimina API keys para tu cuenta.
AutenticaciónEnlace permanente a esta sección
Los endpoints de gestión de claves admiten la autenticación por sesión del panel y la autenticación por API key. Cuando te autenticas con una API key, esa clave debe estar asociada a una cuenta de usuario de SharpAPI; las claves internas o de servicio sin user_id devuelven 400 validation_error.
Seguridad: las operaciones de gestión de API keys son sensibles. Realízalas únicamente desde código del lado del servidor, nunca desde una aplicación del lado del cliente.
Listar API keysEnlace permanente a esta sección
Recupera todas las API keys asociadas con tu cuenta.
GET /api/v1/account/keysEjemplo de peticiónEnlace permanente a esta sección
cURL
curl -X GET "https://api.sharpapi.io/api/v1/account/keys" \
-H "X-API-Key: YOUR_API_KEY"Respuesta (200)Enlace permanente a esta sección
{
"success": true,
"data": [
{
"id": "key_abc123def456",
"id_masked": "...23def456",
"name": "Production",
"tier": "pro",
"is_active": true,
"created_at": "2025-10-15T08:30:00Z",
"updated_at": "2026-02-08T14:22:10Z"
}
],
"meta": {
"count": 1,
"max_keys": 1
}
}meta.max_keys refleja el límite de claves de tu plan: Free/Hobby/Pro = 1, Sharp = 2, Enterprise = personalizado.
Campos del objeto KeyEnlace permanente a esta sección
| Campo | Tipo | Descripción |
|---|---|---|
id | string | Identificador único de la clave. |
id_masked | string | Vista previa enmascarada del identificador de la clave (... más los últimos 8 caracteres). |
name | string | null | Nombre legible de la clave. |
tier | string | Plan de suscripción asociado a la clave. |
is_active | boolean | Indica si la clave está activa actualmente. |
created_at | string | Marca temporal ISO 8601 de creación de la clave. |
updated_at | string | Marca temporal ISO 8601 de la última actualización de la clave. |
Crear API keyEnlace permanente a esta sección
Genera una nueva API key para tu cuenta.
POST /api/v1/account/keysCuerpo de la peticiónEnlace permanente a esta sección
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | No | Nombre descriptivo para la clave, máximo 100 caracteres. Si se omite, la API asigna un nombre predeterminado. |
Ejemplo de peticiónEnlace permanente a esta sección
cURL
curl -X POST "https://api.sharpapi.io/api/v1/account/keys" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Mobile App"}'Respuesta (200)Enlace permanente a esta sección
{
"success": true,
"data": {
"id": "key_new345mno678",
"key": "sk_live_new345mno678...",
"name": "Mobile App",
"tier": "pro"
},
"meta": {
"warning": "This is the only time the key value will be shown. Store it securely."
}
}Importante: el valor completo de key solo se devuelve una vez en el momento de la creación. Almacénalo de forma segura inmediatamente.
Eliminar API keyEnlace permanente a esta sección
Revoca permanentemente una API key.
DELETE /api/v1/account/keys/{keyId}Parámetros de rutaEnlace permanente a esta sección
| Parámetro | Tipo | Descripción |
|---|---|---|
keyId | string | El identificador de la clave que se va a eliminar. |
Ejemplo de peticiónEnlace permanente a esta sección
cURL
curl -X DELETE "https://api.sharpapi.io/api/v1/account/keys/key_xyz789ghi012" \
-H "X-API-Key: YOUR_API_KEY"Respuesta (200)Enlace permanente a esta sección
{
"success": true,
"data": {
"deleted": true,
"key_id": "key_xyz789ghi012",
"message": "API key revoked successfully"
}
}Esta acción es irreversible. Cualquier aplicación que utilice la clave eliminada perderá inmediatamente el acceso a la API. No puedes eliminar la clave con la que te estás autenticando actualmente.
Respuestas de errorEnlace permanente a esta sección
404 Key Not Found
{
"error": {
"code": "not_found",
"message": "Key not found or not owned by you"
}
}400 Cannot Delete Current Key
{
"error": {
"code": "validation_error",
"message": "Cannot delete the API key you are currently using"
}
}Rotar API keyEnlace permanente a esta sección
Genera un nuevo valor de clave y reemplaza una API key existente. De forma predeterminada, la clave anterior se revoca inmediatamente. Puedes solicitar un periodo de gracia de hasta 72 horas.
POST /api/v1/account/keys/{keyId}/rotateParámetros de rutaEnlace permanente a esta sección
| Parámetro | Tipo | Descripción |
|---|---|---|
keyId | string | El identificador de la clave que se va a rotar. |
Cuerpo de la peticiónEnlace permanente a esta sección
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
gracePeriodHours | number | No | Mantiene válida la clave anterior durante este número de horas, de 0 a 72. El valor predeterminado es 0. |
name | string | No | Nombre para la clave de reemplazo. De forma predeterminada, el nombre de la clave anterior. |
Ejemplo de peticiónEnlace permanente a esta sección
cURL
curl -X POST "https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"gracePeriodHours": 0}'Respuesta (200)Enlace permanente a esta sección
{
"success": true,
"data": {
"new_key": {
"id": "key_new789abc012",
"key": "sk_live_rotated789abc012...",
"name": "Production",
"tier": "pro"
},
"old_key": {
"id": "key_abc123def456",
"revoked": true,
"expires_at": null
}
},
"meta": {
"warning": "The new key value is only shown once. Store it securely.",
"message": "Key rotated. Old key has been revoked immediately."
}
}Efecto inmediato: a menos que solicites un periodo de gracia, el valor de la clave anterior se revoca en el instante en que finaliza la rotación. Actualiza la configuración de tu aplicación antes de la siguiente petición a la API. El nuevo valor de key solo se muestra una vez.
Cabeceras de respuestaEnlace permanente a esta sección
Los endpoints de gestión de claves devuelven cabeceras estándar de rate limit:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 294
X-RateLimit-Reset: 1782851940
X-Data-Delay: 0
X-Request-Id: 1782851943426721-511042Buenas prácticasEnlace permanente a esta sección
- Usa nombres descriptivos: nombra las claves según su propósito, como “Production Server” o “Staging”.
- Rota con regularidad: rota las claves periódicamente, como cada 90 días.
- Usa claves separadas por entorno: crea claves distintas para producción, staging y desarrollo.
- Revisa las claves inactivas: identifica y elimina las claves no utilizadas.
- Almacena las claves en un gestor de secretos: usa variables de entorno o un gestor de secretos; nunca incrustes las claves en el código.
- Revoca las claves comprometidas de inmediato: si una clave queda expuesta, elimínala o rótala enseguida.
Endpoints relacionadosEnlace permanente a esta sección
- Información de la cuenta: detalles de la cuenta y acceso a funcionalidades
- Estadísticas de uso: estadísticas de peticiones y de uso
- Autenticación: cómo usar las API keys para autenticarse