ShvIA
TIMELINE
ACESSAR

Docs · Comece aqui

Autenticação e chaves de API

As requisições são autenticadas com uma chave de API. A mesma chave vale nos endpoints compatíveis com OpenAI, nos compatíveis com Anthropic e nos nativos. As poucas operações que gerenciam a própria chave exigem uma sessão, como explicado abaixo.

A chave#

  • Formato: shvia_usr_<id>_<secret>, em que <secret> tem 32 letras e dígitos.
  • Uma chave por conta. Gerar uma chave nova substitui a antiga na hora. Não há chaves nomeadas, nem escopos, nem limites por chave: os limites pertencem à conta.
  • Válida por 365 dias. O prazo é fixo. Gere uma chave nova antes que ela expire.
  • Aparece uma vez. O servidor guarda um hash da chave e uma prévia curta, os primeiros 16 e os últimos 8 caracteres, nunca a chave inteira. Se você perder a chave, gere outra.

Quem pode criar uma chave#

Três condições precisam valer:

  1. Você tem uma conta. O cadastro público fica fechado, a menos que o operador o abra; fora isso, um administrador cria as contas.
  2. O seu grupo de conta tem acesso à API. O operador habilita por grupo. Uma conta recém-criada pode estar num grupo sem ele. Nesse caso o pedido para gerar a chave é recusado com 403 e uma mensagem de que o seu grupo não tem permissão de API. Peça ao seu administrador que mude você de grupo.
  3. Você prova quem é. Gerar uma chave exige a senha da sua conta e uma credencial de sessão: uma chave não gera outra chave.

Crie uma chave no app#

Abra a sua conta, vá à seção de chave de API e escolha gerar uma chave. Copie-a quando ela aparecer. Depois, o app mostra só uma prévia.

Crie uma chave pela API#

Entre para obter um token de sessão e depois peça a chave. A senha é exigida de novo aqui.

bash
curl -s "$SHVIA_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "your password" }'
json
{
  "status": "success",
  "message": "Login realizado com sucesso",
  "data": {
    "access_token": "1|…",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": { "id": 42, "email": "you@example.com", "work_group": "expert", "…": "…" }
  }
}

expires_in é em segundos: 86400 para uma sessão normal, 2592000 quando você também envia "remember_me": true. user é o registro inteiro da conta, com muito mais campos do que os mostrados. Trate-o como informativo: os campos dele não são um contrato.

bash
curl -s "$SHVIA_URL/api/v1/auth/api-key/generate" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "password": "your password" }'
json
{
  "status": "success",
  "message": "API key gerada com sucesso. Guarde-a em local seguro, não será possível visualizá-la novamente.",
  "data": {
    "api_key": "shvia_usr_42_…",
    "expires_at": "2027-10-10T17:43:47.000000Z"
  }
}

O login tem limite de 10 tentativas por minuto por endereço, e 5 falhas seguidas bloqueiam a conta por 30 minutos.

Envie a chave#

Coloque a chave no header Authorization:

bash
curl -s "$SHVIA_URL/v1/models" \
  -H "Authorization: Bearer $SHVIA_API_KEY"

X-API-Key: <key> também é aceito. É o que o SDK da Anthropic envia. Se uma requisição traz um token Authorization: Bearer e também um X-API-Key, vale o token Bearer, mesmo quando ele está errado.

bash
curl -s "$SHVIA_URL/api/v1/auth/verify" \
  -H "X-API-Key: $SHVIA_API_KEY"

Use sempre https://. Uma requisição http:// simples é redirecionada, e alguns clientes perdem o corpo de um POST redirecionado.

Verifique uma chave#

GET/api/v1/auth/verify#

Responde "esta credencial é boa?" e nada mais, o que a torna a chamada certa para um health check na sua integração.

json
{
  "valid": true,
  "via": "apikey",
  "user": { "id": 42, "full_name": "Maria Souza", "email": "maria@example.com", "work_group": "expert", "role": "user", "is_active": true },
  "checked_at": "2026-10-10T17:43:47+00:00"
}

via é apikey para uma chave de API e sanctum para um token de sessão. Uma credencial ruim nunca devolve valid: false; devolve 401.

Revogue ou rotacione uma chave#

DELETE/api/v1/auth/api-key/revoke#

Revogar exige um token de sessão, como gerar. A chave antiga para de funcionar na hora. Para rotacionar, gere uma chave nova: a antiga morre no mesmo instante, então atualize primeiro o seu cofre de segredos e troque rápido.

Quando uma chave é recusada#

Uma chave é recusada com 401 quando é desconhecida, revogada ou expirada, quando a conta está desativada, ou quando o grupo da conta deixou de ter acesso à API. O corpo não diz qual. Nos endpoints /v1 o corpo usa o formato de erro da OpenAI:

json
{
  "error": {
    "message": "Missing or invalid API key. Send it as \"Authorization: Bearer <key>\".",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Nos endpoints /api/v1 é {"message": "Unauthenticated."}. Veja erros.

O que uma chave de API não faz#

Algumas operações precisam de uma pessoa diante de uma tela, não de um script. Com uma chave de API elas respondem 403, ou 401 onde indicado:

  • gerar ou revogar uma chave;
  • salvar ou remover as chaves de provedores de nuvem, e conectar assinaturas de provedores (veja provedores e suas chaves);
  • endpoints de administração, que aceitam só tokens de sessão e respondem 401 a uma chave.

Tokens de sessão#

O token devolvido pelo login funciona nos mesmos endpoints de API que uma chave (nos endpoints /v1 só se o seu grupo tem acesso à API), e também nas operações de conta que uma chave não faz, como gerar uma chave. Ele serve para sessões curtas e para os apps. Para scripts e serviços, use uma chave.

Boas práticas#

  • Leia a chave do ambiente ou de um cofre de segredos.
  • Use uma conta por integração, para que um vazamento fique contido e o uso seja atribuível.
  • Se você registra credenciais para depurar, registre só a parte shvia_usr_<id>_.
  • Guarde o header X-Request-Id das chamadas que falharam. Ele identifica a requisição, e o suporte consegue encontrá-la.