Gestión de API keys

Crea, lista, rota y elimina API keys para tu cuenta.

AutenticaciónPermalink for this section

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 keysPermalink for this section

Recupera todas las API keys asociadas con tu cuenta.


GET /api/v1/account/keys

Ejemplo de peticiónPermalink for this section

cURL


curl -X GET "https://api.sharpapi.io/api/v1/account/keys" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const { data, meta } = await response.json();
 
console.log(`${meta.count}/${meta.max_keys} key slots used`);
for (const key of data) {
  console.log(`${key.name ?? 'Unnamed'}: ${key.id_masked} (${key.is_active})`);
}

Python


import requests
 
response = requests.get(
    'https://api.sharpapi.io/api/v1/account/keys',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
body = response.json()
 
print(f"{body['meta']['count']}/{body['meta']['max_keys']} key slots used")
for key in body['data']:
    print(f"{key['name'] or 'Unnamed'}: {key['id_masked']} ({key['is_active']})")

Respuesta (200)Permalink for this section


{
  "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 KeyPermalink for this section

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 keyPermalink for this section

Genera una nueva API key para tu cuenta.


POST /api/v1/account/keys

Cuerpo de la peticiónPermalink for this section

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ónPermalink for this section

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"}'

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'Mobile App' })
  }
);
const { data, meta } = await response.json();
console.log(`New key: ${data.key}`);
console.warn(meta.warning);

Python


import requests
 
response = requests.post(
    'https://api.sharpapi.io/api/v1/account/keys',
    json={'name': 'Mobile App'},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
body = response.json()
print(f"New key: {body['data']['key']}")
print(body['meta']['warning'])

Respuesta (200)Permalink for this section


{
  "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 keyPermalink for this section

Revoca permanentemente una API key.


DELETE /api/v1/account/keys/{keyId}

Parámetros de rutaPermalink for this section

Parámetro	Tipo	Descripción
`keyId`	string	El identificador de la clave que se va a eliminar.

Ejemplo de peticiónPermalink for this section

cURL


curl -X DELETE "https://api.sharpapi.io/api/v1/account/keys/key_xyz789ghi012" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys/key_xyz789ghi012',
  {
    method: 'DELETE',
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
);
const { data } = await response.json();
console.log(`Deleted key: ${data.key_id}`);

Python


import requests
 
response = requests.delete(
    'https://api.sharpapi.io/api/v1/account/keys/key_xyz789ghi012',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
data = response.json()['data']
print(f"Deleted key: {data['key_id']}")

Respuesta (200)Permalink for this section


{
  "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 errorPermalink for this section

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 keyPermalink for this section

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}/rotate

Parámetros de rutaPermalink for this section

Parámetro	Tipo	Descripción
`keyId`	string	El identificador de la clave que se va a rotar.

Cuerpo de la peticiónPermalink for this section

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ónPermalink for this section

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}'

JavaScript


const response = await fetch(
  'https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ gracePeriodHours: 0 })
  }
);
const { data, meta } = await response.json();
console.log(`New key value: ${data.new_key.key}`);
console.warn(meta.warning);

Python


import requests
 
response = requests.post(
    'https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate',
    json={'gracePeriodHours': 0},
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
body = response.json()
print(f"New key: {body['data']['new_key']['key']}")
print(body['meta']['message'])

Respuesta (200)Permalink for this section


{
  "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 respuestaPermalink for this section

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-511042

Buenas prácticasPermalink for this section

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 relacionadosPermalink for this section

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