Comece Aqui

Autenticação

Entenda o fluxo de autenticação JWT de duas fases da Keyspot Partner API, com exemplos de código e boas práticas de segurança.

Visão geral

A Partner API usa autenticação JWT (JSON Web Token) em duas fases:

Fase 1 — Obter token: envie suas credenciais (X-API-Key + X-API-Secret) e receba um token JWT
Fase 2 — Usar token: inclua o token como Bearer no header Authorization de todas as rotas protegidas

Os exemplos desta página usam o ambiente sandbox (https://sandbox-partner-api.keyspot.com.br). Para produção, use https://partner-api.keyspot.com.br.

Fase 1 — Gerar token

Envie suas credenciais via headers para o endpoint de autenticação:

curl -X POST https://sandbox-partner-api.keyspot.com.br/v1/auth/token \
  -H "X-API-Key: ks_live_k9xv2mp8qr1nl4wz7jy0ea3sd6fh5tg2u" \
  -H "X-API-Secret: ks_secret_c8bn1mq4pk7rv0xj3yw6za9oe2iu5lhd"

async function getToken(apiKey: string, apiSecret: string): Promise<string> {
  const response = await fetch("https://sandbox-partner-api.keyspot.com.br/v1/auth/token", {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-API-Secret": apiSecret,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Auth failed: ${error.code} - ${error.error}`);
  }

  const { data } = await response.json();
  return data.token;
}

const token = await getToken("ks_live_k9xv2mp8qr1nl4wz7jy0ea3sd6fh5tg2u", "ks_secret_c8bn1mq4pk7rv0xj3yw6za9oe2iu5lhd");

import requests

def get_token(api_key: str, api_secret: str) -> str:
    response = requests.post(
        "https://sandbox-partner-api.keyspot.com.br/v1/auth/token",
        headers={
            "X-API-Key": api_key,
            "X-API-Secret": api_secret,
        },
    )
    response.raise_for_status()
    return response.json()["data"]["token"]

token = get_token("ks_live_k9xv2mp8qr1nl4wz7jy0ea3sd6fh5tg2u", "ks_secret_c8bn1mq4pk7rv0xj3yw6za9oe2iu5lhd")

Resposta de sucesso

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

Campo	Tipo	Descrição
`token`	string	Token JWT assinado com HS256
`expiresIn`	integer	Tempo de expiração em segundos (3600 = 1 hora)
`tokenType`	string	Tipo do token (sempre `Bearer`)

Possíveis erros

Status	Código	Causa
401	`MISSING_CREDENTIALS`	Headers `X-API-Key` e/ou `X-API-Secret` ausentes
401	`INVALID_API_KEY`	API Key não encontrada no sistema
401	`INVALID_API_SECRET`	API Secret não confere com a API Key
403	`API_DISABLED`	Acesso à API desabilitado para este cliente
403	`IP_BLOCKED`	IP da requisição não está na lista de IPs permitidos
500	`NO_DATABASE`	Banco de dados do cliente não configurado

Fase 2 — Usar o token

Inclua o token no header Authorization com o prefixo Bearer:

curl https://sandbox-partner-api.keyspot.com.br/v1/properties?fields=code,title \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Se o token estiver ausente, malformado ou expirado, a API retorna 401 com código MISSING_TOKEN ou INVALID_TOKEN.

Renovação de token

O token expira em 1 hora (3600 segundos). Você tem duas estratégias para lidar com a renovação:

Armazene o momento de emissão do token e renove-o antes de expirar (por exemplo, a cada 50 minutos):

let token: string;
let tokenIssuedAt: number;

async function ensureValidToken(): Promise<string> {
  const now = Date.now();
  const tokenAge = (now - tokenIssuedAt) / 1000;

  // Renovar se faltam menos de 10 minutos
  if (!token || tokenAge > 3000) {
    token = await getToken(API_KEY, API_SECRET);
    tokenIssuedAt = now;
  }

  return token;
}

Intercepte erros 401 e gere um novo token automaticamente:

async function apiCall(url: string): Promise<any> {
  let response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (response.status === 401) {
    token = await getToken(API_KEY, API_SECRET);
    response = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    });
  }

  return response.json();
}

Segurança

Nunca exponha suas credenciais (API Key e API Secret) em código client-side, repositórios públicos ou logs.

Boas práticas:

Armazene credenciais em variáveis de ambiente ou gerenciadores de secrets
Use HTTPS em todas as requisições
Não compartilhe tokens JWT entre aplicações diferentes
Implemente renovação automática de token
Se suas credenciais forem comprometidas, solicite novas via chamado no CRM imediatamente: https://crm.keyspot.com.br/support/tickets

A Keyspot pode configurar uma lista de IPs permitidos para suas credenciais. Se o IP da requisição não estiver na lista, a API retorna 403 IP_BLOCKED. Solicite a inclusão de novos IPs via chamado no CRM: https://crm.keyspot.com.br/support/tickets.

Próximos passos

Quickstart

Faça sua primeira chamada à API em 5 minutos.

Boas Práticas

Paginação, retry com backoff e checklist de produção.

Was this page helpful?

Last updated today

Built with Documentation.AI