Autenticação

A API é autenticada por chave de API. Cada chave pertence a uma loja e é gerada no painel, em Integrações → API.

Gerando uma chave

No painel, vá em Integrações → API → Nova chave. Dê um nome e marque os escopos que a integração precisa. A chave completa (gp_live_… ou gp_test_…) é exibida uma única vez: copie e guarde em local seguro. Guardamos apenas um hash e não conseguimos mostrá-la de novo.

Enviando a chave

Envie a chave no header Authorization como Bearer token:

Authorization: Bearer gp_live_a4e60a93...

Como alternativa, o header x-api-key também é aceito:

x-api-key: gp_live_a4e60a93...

Escopos

Cada chave tem uma lista de escopos. O escopo decide quais rotas a chave pode chamar.

Na criação, nenhum escopo vem marcado, e ao menos um é obrigatório.
Quem tem acesso a Integrações no painel pode editar os escopos de uma chave ativa. A lista nova vale na requisição seguinte, sem trocar a chave.
Marque só o que a integração usa. students:read dá acesso a dados pessoais de alunos, e subscriptions:read ao e-mail, CPF/CNPJ e telefone de quem assina.

Escopo	O que libera
`charges:write`	Criar cobranças
`charges:read`	Consultar cobranças
`payments:read`	Listar pagamentos e vendedores
`subscriptions:read`	Listar assinaturas, com os dados do cliente (dado pessoal)
`courses:read`	Ler cursos, módulos, aulas e turmas
`students:read`	Ler alunos, matrículas e progresso (dado pessoal)
`mcp`	Usar a chave no servidor MCP

Escopo exigido por rota

Rota	Escopo
`POST /v1/charges`	`charges:write`
`GET /v1/charges/{id}`	`charges:read`
`GET /v1/payments`	`payments:read`
`GET /v1/sales-reps`	`payments:read`
`GET /v1/subscriptions`	`subscriptions:read`
`GET /v1/courses`, `GET /v1/courses/{id}`, `GET /v1/cohorts`	`courses:read`
`GET /v1/students`, `GET /v1/students/{id}`, `GET /v1/students/{id}/progress`	`students:read`
Servidor MCP	`mcp`

A Referência da API mostra o escopo de cada operação.

Chave sem o escopo

Uma chave válida sem o escopo da rota recebe 403, e a rota não é executada. O campo requiredScope diz qual escopo pedir:

{
  "error": {
    "type": "insufficient_scope",
    "message": "Esta chave de API não tem o escopo students:read.",
    "requiredScope": "students:read"
  }
}

O servidor MCP recusa a chave sem o escopo mcp do mesmo jeito que recusa uma chave inválida.

Chaves criadas antes dos escopos

Toda chave criada antes dos escopos continua funcionando como antes. Ela tem charges:write, charges:read, payments:read e mcp. Ela não tem courses:read nem students:read: para ler a área de membros, edite os escopos da chave no painel. Nenhuma chave existente ganhou subscriptions:read. Para listar assinaturas, marque o escopo na chave pelo painel.

Boas práticas

Nunca exponha a chave no navegador. Use a chave somente no seu servidor, com os escopos que a integração precisa. Para cobrar no front-end, use a checkoutUrl retornada pela cobrança.

Revogue chaves comprometidas no painel. O acesso é cortado na hora.
Use chaves de teste (gp_test_) em desenvolvimento e live (gp_live_) em produção. As rotas de leitura devolvem os mesmos dados da loja para as duas.
Uma requisição sem chave válida, ou com chave revogada, retorna 401 antes de conferir o escopo:

{
  "error": {
    "type": "authentication",
    "message": "Chave de API inválida."
  }
}

Introdução

Guias

Gerando uma chave

Enviando a chave

Escopos

Escopo exigido por rota

Chave sem o escopo

Chaves criadas antes dos escopos

Boas práticas

​Gerando uma chave

​Enviando a chave

​Escopos

​Escopo exigido por rota

​Chave sem o escopo

​Chaves criadas antes dos escopos

​Boas práticas

Gerando uma chave

Enviando a chave

Escopos

Escopo exigido por rota

Chave sem o escopo

Chaves criadas antes dos escopos

Boas práticas