Autenticação
Como autenticar suas requisições à API OctaGym usando API Keys.
Autenticação
A API OctaGym utiliza API Keys para autenticação. Cada chave pertence a uma empresa e alcança somente os escopos concedidos na criação.
Formato da API Key
og_live_8f92k3d7a9b2c4e6f8g0h1i2j3...Todas as chaves usam o prefixo og_live_. Chaves antigas com prefixo ea_live_ continuam válidas.
Não existe ambiente de teste separado
A API não tem sandbox nem chave og_test_: a chave opera sobre os dados reais da sua empresa. Para
desenvolver com segurança, crie uma chave com escopos somente de leitura e valide as escritas
em uma empresa de homologação.
Importante
A API Key é exibida apenas uma vez no momento da criação. Se você perder a chave, será necessário gerar uma nova.
Escopos
Uma chave só alcança os endpoints dos escopos concedidos. Endpoint fora deles responde 403 com o
código INSUFFICIENT_SCOPE; endpoint fora da API pública responde 403 ENDPOINT_NOT_PUBLIC,
independentemente dos escopos.
| Escopo | O que libera |
|---|---|
members:read | Listar e consultar alunos, medições e histórico de check-ins |
members:write | Cadastrar e atualizar alunos, registrar medições |
memberships:read | Consultar mensalidades, vigência e status de pagamento |
memberships:write | Criar, alterar, cancelar e congelar mensalidades |
plans:read | Consultar planos |
classes:read | Consultar grade, modalidades e vagas |
classes:write | Reservar e cancelar vagas em aulas |
workouts:read | Consultar programas de treino |
workouts:write | Criar programas de treino |
exercises:read | Consultar o catálogo de exercícios |
trainers:read | Consultar instrutores |
metrics:read | Consultar indicadores agregados (MRR, churn, ocupação) |
access:read | Consultar ocupação atual e check-ins |
access:write | Registrar check-in e check-out |
Marcar um escopo de escrita concede automaticamente a leitura do mesmo recurso — toda rota de escrita lê antes de gravar.
Conceda o mínimo
Uma chave para sincronizar alunos com o seu CRM precisa de members:read, e só. Se ela vazar, o
estrago fica limitado ao que você concedeu.
Validade e rotação
Toda chave pode ter validade (padrão sugerido: 90 dias). Chave expirada responde 401 com a
mensagem API key has expired — o remédio é gerar outra em Configurações → Desenvolvedor.
A tela mostra a coluna Último uso de cada chave. Chave sem uso há meses normalmente é integração desativada que ninguém revogou: revogue.
Obtendo suas Chaves
Acesse o painel de API Keys
Navegue até Configurações → Desenvolvedor no painel do OctaGym.
Gere uma nova chave
Clique em "Nova Chave", dê um nome que identifique a integração, marque os escopos que ela precisa e escolha a validade. Prefira uma chave por integração: assim revogar uma não derruba as outras.
Copie e armazene com segurança
A chave completa só é exibida uma vez. Copie e armazene em um local seguro como:
- Variáveis de ambiente
- Secrets manager (AWS, GCP, Azure)
- HashiCorp Vault
Formato do Header
Inclua o header Authorization em todas as requisições:
Authorization: Bearer og_live_sua_chave_aqui
Content-Type: application/jsonExemplos de Autenticação
curl -X GET https://dashboard.octagym.ai/api/v1/members \
-H "Authorization: Bearer og_live_sua_chave_aqui" \
-H "Content-Type: application/json"const apiKey = process.env.OCTAGYM_API_KEY;
const response = await fetch('https://dashboard.octagym.ai/api/v1/members', {
method: 'GET',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
});
const data = await response.json();
// Cliente reutilizável
class OctaGymClient {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://dashboard.octagym.ai/api/v1';
}
async request(endpoint, options = {}) {
const response = await fetch(`${this.baseUrl}${endpoint}`, {
...options,
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json',
...options.headers
}
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error?.message || 'API Error');
}
return response.json();
}
}
const client = new OctaGymClient(process.env.OCTAGYM_API_KEY);
import os
import requests
api_key = os.environ.get('OCTAGYM_API_KEY')
headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}
response = requests.get(
'https://dashboard.octagym.ai/api/v1/members',
headers=headers
)
data = response.json()
# Classe cliente reutilizável
class OctaGymClient:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = 'https://dashboard.octagym.ai/api/v1'
self.session = requests.Session()
self.session.headers.update({
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
})
def get(self, endpoint, params=None):
response = self.session.get(f'{self.base_url}{endpoint}', params=params)
response.raise_for_status()
return response.json()
def post(self, endpoint, data):
response = self.session.post(f'{self.base_url}{endpoint}', json=data)
response.raise_for_status()
return response.json()
client = OctaGymClient(os.environ['OCTAGYM_API_KEY'])<?php
$apiKey = getenv('OCTAGYM_API_KEY');
$baseUrl = 'https://dashboard.octagym.ai/api/v1';
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $baseUrl . '/members',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
// Classe cliente
class OctaGymClient {
private $apiKey;
private $baseUrl = 'https://dashboard.octagym.ai/api/v1';
public function __construct($apiKey) {
$this->apiKey = $apiKey;
}
public function request($method, $endpoint, $data = null) {
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $this->baseUrl . $endpoint,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $this->apiKey,
'Content-Type: application/json'
]
]);
if ($data) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
}
$client = new OctaGymClient(getenv('OCTAGYM_API_KEY'));
Vinculação com a Empresa
Cada API Key pertence a uma empresa (o CNPJ que contrata o OctaGym; pode ter várias unidades). Isso garante:
- Isolamento de dados: a chave só alcança recursos da empresa vinculada
- Controle de acesso: cada empresa administra as próprias chaves
- Auditoria: cada requisição é rastreada pela chave que a fez
Empresa com várias unidades
A chave não tem "unidade ativa" como a sessão do painel: ela enxerga todas as unidades da empresa.
Nas escritas que dependem de unidade (check-in, check-out, matrícula), envie store_id no corpo.
Gerenciamento de Chaves
Listando Chaves
No painel de chaves você vê, para cada uma:
- Prefixo: primeiros caracteres, para identificação
- Escopos: o que a chave alcança
- Último uso: quando ela autenticou pela última vez (
Nunca usadase ainda não usou) - Expira em: a validade, ou
Sem expiração
Revogando Chaves
Para revogar uma chave comprometida:
- Acesse Configurações → Desenvolvedor
- Localize a chave pelo prefixo
- Clique no ícone de revogar
- Confirme a ação
A revogação é imediata e irreversível. Todas as requisições usando esta chave passarão a retornar 401 Unauthorized.
Rotação de Chaves
Recomendamos rotacionar suas chaves periodicamente (a cada 90 dias):
- Gere uma nova chave
- Atualize suas aplicações para usar a nova chave
- Monitore que tudo está funcionando
- Revogue a chave antiga
Erros de Autenticação
| Código | Erro | Descrição | Solução |
|---|---|---|---|
401 | Missing or invalid Authorization header | Header ausente ou malformado | Adicione Authorization: Bearer og_live_... |
401 | Invalid API key | Chave não encontrada ou formato incorreto | Confira a chave; se perdeu, gere outra |
401 | API key is inactive | Chave desativada | Gere uma nova chave |
401 | API key has been revoked | Chave revogada no painel | Gere uma nova chave |
401 | API key has expired | Passou da validade | Gere uma nova chave em Configurações → Desenvolvedor |
401 | API key has no scopes granted | Chave sem nenhum escopo | Gere uma nova chave marcando os escopos |
403 | INSUFFICIENT_SCOPE | A chave não tem o escopo do endpoint | Veja details.required_scope e gere uma chave com ele |
403 | ENDPOINT_NOT_PUBLIC | O endpoint não faz parte da API pública | Consulte a referência |
405 | METHOD_NOT_ALLOWED | O endpoint não aceita esse método pela API | Veja details.allowed_methods |
Exemplo de Resposta de Erro
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "API Key inválida ou ausente"
}
}Boas Práticas de Segurança
Faça
- Armazene chaves em variáveis de ambiente
- Use secrets managers em produção
- Conceda o menor escopo que a integração precisa
- Use uma chave por integração, para revogar uma sem derrubar as outras
- Defina validade e rotacione periodicamente (a cada 90 dias)
- Acompanhe a coluna Último uso e revogue chave esquecida
Não Faça
- Commitar chaves em repositórios Git
- Expor chaves em código front-end ou logs
- Compartilhar a mesma chave entre integrações diferentes
- Conceder escopo de escrita a uma integração que só lê
- Deixar chaves antigas ativas sem uso
Testando a Autenticação
Verifique se sua chave está funcionando:
curl -X GET https://dashboard.octagym.ai/api/v1/members \
-H "Authorization: Bearer og_live_sua_chave_aqui"Resposta de sucesso:
{
"success": true,
"data": [],
"pagination": {
"page": 1,
"limit": 20,
"total": 0,
"pages": 0
}
}Resposta de erro:
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "API Key inválida"
}
}Suporte
Problemas com autenticação?
- Email: suporte@octagym.ai
- Documentação: Início Rápido