Autenticação

Toda chamada à API Velix requer um Bearer token no header Authorization.

Authorization: Bearer SEU_TOKEN_AQUI

---

Escopos

Cada token possui um conjunto de escopos que define o que pode ser feito:

Escopo	Acesso
tenant:read	Leitura de configurações do tenant
tenant:write	Edição de configurações
checkin:process	Processar check-ins biométricos
persons:manage	CRUD de pessoas e enroll biométrico
events:manage	Criação e gestão de eventos
webhooks:manage	Configuração de webhooks

Os escopos são configurados pela equipe Velix durante o onboarding. Entre em contato para ampliar os escopos de um token existente.

---

Ambiente sandbox

Para desenvolvimento e testes, use o ambiente sandbox:

Parâmetro	Valor
URL base	https://sandbox-api.velixbiometrics.com
Token	fornecido pela equipe Velix
Biometria	simulada (FACE_ENGINE_MODE=stub)
Reset	dados apagados toda noite às 03h

O sandbox inclui 3 pessoas e 1 evento de exemplo pré-cadastrados.

---

Erros de autenticação

Código HTTP	Código de erro	Significado
401	unauthorized	Token ausente ou inválido
403	forbidden	Token válido, mas sem escopo suficiente
401	token_expired	Token expirado — solicite renovação

---

Exemplo de header por linguagem

TypeScript

import { VelixClient } from '@velix/sdk';

const velix = new VelixClient({
  apiUrl: process.env.VELIX_API_URL ?? 'https://api.velixbiometrics.com',
  apiKey: process.env.VELIX_API_KEY!,
});

JavaScript

const { VelixClient } = require('@velix/sdk');

const velix = new VelixClient({
  apiUrl: process.env.VELIX_API_URL ?? 'https://api.velixbiometrics.com',
  apiKey: process.env.VELIX_API_KEY,
});

PHP

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://api.velixbiometrics.com',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('VELIX_API_KEY')],
]);

C#

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("VELIX_API_KEY"));

Java

.header("Authorization", "Bearer " + System.getenv("VELIX_API_KEY"))

Rust

.bearer_auth(std::env::var("VELIX_API_KEY").unwrap())

Go

req.Header.Set("Authorization", "Bearer " + os.Getenv("VELIX_API_KEY"))

Kotlin

val client = VelixClient {
    apiUrl = "https://api.velixbiometrics.com"
    apiKey = System.getenv("VELIX_API_KEY")
}

Ruby

client = Velix::Client.new(
  api_url: "https://api.velixbiometrics.com",
  api_key: ENV["VELIX_API_KEY"]
)

Swift

let client = VelixClient(config: VelixConfig(
    apiURL: URL(string: "https://api.velixbiometrics.com")!,
    apiKey: ProcessInfo.processInfo.environment["VELIX_API_KEY"]!
))

Dart

final client = VelixClient(VelixConfig(
  apiUrl: 'https://api.velixbiometrics.com',
  apiKey: Platform.environment['VELIX_API_KEY']!,
));

Elixir

config :velix,
  api_url: "https://api.velixbiometrics.com",
  api_key: System.fetch_env!("VELIX_API_KEY")

Lua

local client = velix.Client.new({
  api_url = "https://api.velixbiometrics.com",
  api_key = os.getenv("VELIX_API_KEY"),
})

PowerShell

Connect-Velix -ApiUrl "https://api.velixbiometrics.com" -ApiKey $env:VELIX_API_KEY

Delphi

Client := TVelixClient.Create(
  'https://api.velixbiometrics.com',
  GetEnvironmentVariable('VELIX_API_KEY')
);

cURL

curl https://api.velixbiometrics.com/v1/auth/me \
  -H "Authorization: Bearer $VELIX_API_KEY"