Gerenciamento de API Keys

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

AutenticaçãoPermalink for this section

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

Recupere todas as API keys associadas à sua conta.


GET /api/v1/account/keys

Exemplo de RequisiçãoPermalink 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 } = 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)Permalink for this section


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

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

Gere uma nova API key para sua conta.


POST /api/v1/account/keys

Corpo da RequisiçãoPermalink for this section

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

Exemplo de RequisiçãoPermalink 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 } = 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)Permalink for this section


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

Revogue e exclua permanentemente uma API key.


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

Parâmetros de CaminhoPermalink for this section

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

Exemplo de RequisiçãoPermalink 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 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)Permalink for this section


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

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

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

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

Exemplo de RequisiçãoPermalink 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"

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)Permalink for this section


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

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áticasPermalink for this section

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

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