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.

EscopoO que libera
members:readListar e consultar alunos, medições e histórico de check-ins
members:writeCadastrar e atualizar alunos, registrar medições
memberships:readConsultar mensalidades, vigência e status de pagamento
memberships:writeCriar, alterar, cancelar e congelar mensalidades
plans:readConsultar planos
classes:readConsultar grade, modalidades e vagas
classes:writeReservar e cancelar vagas em aulas
workouts:readConsultar programas de treino
workouts:writeCriar programas de treino
exercises:readConsultar o catálogo de exercícios
trainers:readConsultar instrutores
metrics:readConsultar indicadores agregados (MRR, churn, ocupação)
access:readConsultar ocupação atual e check-ins
access:writeRegistrar 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/json

Exemplos 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 usada se ainda não usou)
  • Expira em: a validade, ou Sem expiração

Revogando Chaves

Para revogar uma chave comprometida:

  1. Acesse Configurações → Desenvolvedor
  2. Localize a chave pelo prefixo
  3. Clique no ícone de revogar
  4. 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):

  1. Gere uma nova chave
  2. Atualize suas aplicações para usar a nova chave
  3. Monitore que tudo está funcionando
  4. Revogue a chave antiga

Erros de Autenticação

CódigoErroDescriçãoSolução
401Missing or invalid Authorization headerHeader ausente ou malformadoAdicione Authorization: Bearer og_live_...
401Invalid API keyChave não encontrada ou formato incorretoConfira a chave; se perdeu, gere outra
401API key is inactiveChave desativadaGere uma nova chave
401API key has been revokedChave revogada no painelGere uma nova chave
401API key has expiredPassou da validadeGere uma nova chave em Configurações → Desenvolvedor
401API key has no scopes grantedChave sem nenhum escopoGere uma nova chave marcando os escopos
403INSUFFICIENT_SCOPEA chave não tem o escopo do endpointVeja details.required_scope e gere uma chave com ele
403ENDPOINT_NOT_PUBLICO endpoint não faz parte da API públicaConsulte a referência
405METHOD_NOT_ALLOWEDO endpoint não aceita esse método pela APIVeja 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?

On this page