Gerenciamento de API Keys

Crie, liste, faça a rotação e exclua API keys da sua conta.

Autenticação

Todos os endpoints de gerenciamento de keys exigem autenticação por meio de uma API key existente. Disponível para todos os tiers.

Segurança: As operações de gerenciamento de API keys são sensíveis. Execute-as apenas a partir de código no lado do servidor, nunca de uma aplicação no lado do cliente.

Listar API Keys

Recupere todas as API keys associadas à sua conta.


GET /api/v1/account/keys

Exemplo de Requisição

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 } = await response.json();
 
for (const key of data) {
  console.log(`${key.name}: ${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'}
)
keys = response.json()['data']
 
for key in keys:
    print(f"{key['name']}: {key['id_masked']} ({key['is_active']})")

Resposta (200)


{
  "data": [
    {
      "id": "key_abc123def456",
      "id_masked": "sharpapi_...f456",
      "name": "Production",
      "tier": "pro",
      "is_active": true,
      "created_at": "2025-10-15T08:30:00Z",
      "updated_at": "2026-02-08T14:22:10Z"
    },
    {
      "id": "key_xyz789ghi012",
      "id_masked": "sharpapi_...i012",
      "name": "Staging",
      "tier": "pro",
      "is_active": true,
      "created_at": "2026-01-05T12:00:00Z",
      "updated_at": "2026-02-07T09:15:30Z"
    }
  ],
  "meta": {
    "count": 2,
    "total": 2,
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": false,
      "next_offset": null
    },
    "updated_at": "2026-02-08T14:55:00Z"
  }
}

Campos do Objeto Key

Campo	Tipo	Descrição
`id`	string	Identificador único da key
`id_masked`	string	Visualização mascarada da key (primeiros e últimos caracteres visíveis)
`name`	string \| null	Nome legível da key
`tier`	string	Tier de assinatura associado à key
`is_active`	boolean	Indica se a key está atualmente ativa
`created_at`	string	Timestamp ISO 8601 da criação da key
`updated_at`	string	Timestamp ISO 8601 da última atualização da key

Criar API Key

Gere uma nova API key para sua conta.


POST /api/v1/account/keys

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Um nome descritivo para a key (ex.: “Production”, “Mobile App”)

Exemplo de Requisição

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 } = await response.json();
console.log(`New key: ${data.key}`);
// IMPORTANT: Store this key securely. It will not be shown again.

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'}
)
new_key = response.json()['data']
print(f"New key: {new_key['key']}")
# IMPORTANT: Store this key securely. It will not be shown again.

Resposta (201)


{
  "data": {
    "id": "key_new345mno678",
    "key": "sharpapi_new345mno678pqr901stu234vwx567",
    "name": "Mobile App",
    "tier": "pro"
  }
}

Importante: O valor completo da key é retornado apenas uma vez no momento da criação. Armazene-o com segurança imediatamente. Requisições subsequentes mostrarão apenas a visualização id_masked.

Excluir API Key

Revogue e exclua permanentemente uma API key.


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

Parâmetros de Caminho

Parâmetro	Tipo	Descrição
`keyId`	string	O `key_id` da key a ser excluída

Exemplo de Requisição

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 result = await response.json();
console.log(`Deleted key: ${result.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'}
)
result = response.json()
print(f"Deleted key: {result['key_id']}")

Resposta (200)


{
  "deleted": true,
  "key_id": "key_xyz789ghi012",
  "message": "API key revoked successfully"
}

Esta ação é irreversível. Qualquer aplicação que utilize a key excluída perderá imediatamente o acesso à API. Você não pode excluir a key que está sendo usada para autenticar a requisição atual.

Respostas de Erro

404 Key Não Encontrada


{
  "error": {
    "code": "not_found",
    "message": "API key not found",
    "docs": "https://docs.sharpapi.io/en/api-reference/account-keys"
  }
}

400 Não é Possível Excluir a Key Atual


{
  "error": {
    "code": "validation_error",
    "message": "Cannot delete the API key used to authenticate this request",
    "docs": "https://docs.sharpapi.io/en/api-reference/account-keys"
  }
}

Rotacionar API Key

Gere um novo valor de key para uma API key existente. A key antiga é imediatamente revogada e substituída por uma nova.


POST /api/v1/account/keys/{keyId}/rotate

Parâmetros de Caminho

Parâmetro	Tipo	Descrição
`keyId`	string	O `key_id` da key a ser rotacionada

Exemplo de Requisição

cURL


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

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' }
  }
);
const { data } = await response.json();
console.log(`New key value: ${data.key}`);
// IMPORTANT: Update your application configuration with the new key immediately.

Python


import requests
 
response = requests.post(
    'https://api.sharpapi.io/api/v1/account/keys/key_abc123def456/rotate',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
rotated = response.json()['data']
print(f"New key: {rotated['key']}")
# IMPORTANT: Update your application configuration with the new key immediately.

Resposta (200)


{
  "data": {
    "key_id": "key_abc123def456",
    "name": "Production",
    "key": "sharpapi_rotated789abc012def345ghi678jkl",
    "key_preview": "sharpapi_...jkl",
    "status": "active",
    "rotated_at": "2026-02-08T15:10:00Z",
    "previous_key_revoked": true
  },
  "meta": {
    "updated_at": "2026-02-08T15:10:00Z"
  }
}

Efeito imediato: O valor da key anterior é revogado no instante em que a rotação é concluída. Atualize a configuração da sua aplicação antes da próxima requisição à API. O novo valor da key é exibido apenas uma vez.

Dica: Se você estiver rotacionando a key que está sendo usada para autenticar a requisição atual, a rotação será bem-sucedida, mas você deverá usar a nova key em todas as requisições subsequentes.

Cabeçalhos de Resposta

Todos os endpoints de gerenciamento de keys retornam cabeçalhos padrão de rate limit:


X-RateLimit-Limit: 300
X-RateLimit-Remaining: 294
X-RateLimit-Reset: 1707401400
X-Data-Delay: 0
X-Request-Id: req_keys123xyz

Boas Práticas

Use nomes descritivos - Nomeie as keys de acordo com sua finalidade (ex.: “Production Server”, “Staging”, “Mobile App”) para identificá-las facilmente depois
Faça a rotação regularmente - Rotacione as keys periodicamente (ex.: a cada 90 dias) como boa prática de segurança
Use keys separadas por ambiente - Crie keys distintas para produção, staging e desenvolvimento
Revise keys inativas - Identifique e remova keys não utilizadas
Armazene keys em um gerenciador de segredos - Use variáveis de ambiente ou um gerenciador de segredos, nunca insira keys diretamente no código
Revogue keys comprometidas imediatamente - Se uma key for exposta, exclua-a ou rotacione-a imediatamente

Endpoints Relacionados

Informações da Conta - Detalhes da conta e acesso a recursos
Estatísticas de Uso - Estatísticas de requisições e uso
Autenticação - Como usar API keys para autenticação