Gerenciamento de API Keys

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

AutenticaçãoPermalink for this section

Os endpoints de gerenciamento de keys suportam autenticação por sessão do painel e autenticação por API key. Ao autenticar com uma API key, essa key precisa estar associada a uma conta de usuário do SharpAPI; keys internas ou de serviço sem user_id retornam 400 validation_error.

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, 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']})")

Resposta (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 reflete o limite de keys do seu tier: Free/Hobby/Pro = 1, Sharp = 2, Enterprise = personalizado.

Campos do Objeto KeyPermalink for this section

Campo	Tipo	Descrição
`id`	string	Identificador único da key.
`id_masked`	string	Visualização mascarada do identificador da key (`...` mais os 8 últimos caracteres).
`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	Não	Nome descritivo para a key, no máximo 100 caracteres. Se omitido, a API atribui um nome padrão.

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, 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'])

Resposta (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: O valor completo da key é retornado apenas uma vez no momento da criação. Armazene-o com segurança imediatamente.

Excluir API KeyPermalink for this section

Revogue 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 identificador 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 { 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']}")

Resposta (200)Permalink for this section


{
  "success": true,
  "data": {
    "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": "Key not found or not owned by you"
  }
}

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


{
  "error": {
    "code": "validation_error",
    "message": "Cannot delete the API key you are currently using"
  }
}

Rotacionar API KeyPermalink for this section

Gere um novo valor de key e substitua uma API key existente. Por padrão, a key antiga é revogada imediatamente. Você pode solicitar um período de carência de até 72 horas.


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

Parâmetros de CaminhoPermalink for this section

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

Corpo da RequisiçãoPermalink for this section

Campo	Tipo	Obrigatório	Descrição
`gracePeriodHours`	number	Não	Mantém a key antiga válida por esta quantidade de horas, de `0` a `72`. O padrão é `0`.
`name`	string	Não	Nome para a key substituta. Por padrão, o nome da key antiga.

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" \
  -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'])

Resposta (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."
  }
}

Efeito imediato: A menos que você solicite um período de carência, 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.

Cabeçalhos de RespostaPermalink for this section

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: 1782851940
X-Data-Delay: 0
X-Request-Id: 1782851943426721-511042

Boas PráticasPermalink for this section

Use nomes descritivos - Nomeie as keys de acordo com sua finalidade, como “Production Server” ou “Staging”.
Faça a rotação regularmente - Rotacione as keys periodicamente, como a cada 90 dias.
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