Começo

Autenticação

Access Control usa OAuth 2.0 client credentials no Keycloak da Ingresse. Partner Reports exige um token com as claims email e sub (UUID); tokens de client_credentials emitidos hoje não trazem a claim email, então um client credentials como o do exemplo abaixo é rejeitado. O webhook não usa token: a autenticidade é verificada pela assinatura HMAC da entrega.

Obter um token

Faça uma requisição POST ao endpoint de token do realm da Ingresse com suas credenciais de cliente. O exemplo abaixo usa o grant client_credentials, aceito pela Access Control. O token retornado deve ser enviado como Authorization: Bearer <token> nas demais chamadas.

cURL

curl --request POST \
  --url https://<AUTH_PROD_HOST>/realms/ingresse/protocol/openid-connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=<SEU_CLIENT_ID>' \
  --data 'client_secret=<SEU_CLIENT_SECRET>'

Exemplo de resposta

JSON

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "expires_in": 604800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0
}

Este token não serve para a Partner Reports

Um token obtido por client_credentials, como o do exemplo acima, não carrega a claim email nem um sub em formato UUID. A Partner Reports exige as duas e rejeita esse token com 401:

JSON

{
  "code": "unauthorized",
  "message": "invalid token: invalid authentication token: missing email"
}

Para consultar a Partner Reports, use um token que carregue essas duas claims — os tokens de client_credentials emitidos hoje não as trazem. Fale com seu account manager/equipe de integrações sobre como obtê-lo.

Campo	Tipo	Descrição
`access_token`	string (JWT)	Token a ser enviado no header Authorization.
`expires_in`	int	Tempo de vida do token em segundos.
`refresh_expires_in`	int	Tempo de vida do refresh token em segundos. 0 indica que não há refresh token.
`token_type`	string	Sempre Bearer.
`not-before-policy`	int	Timestamp a partir do qual o token é válido (0 desativa a política).
`scope`	string	Escopos concedidos ao token — variam por client. Omitido do exemplo acima por esse motivo.

Ciclo de vida do token

Renove proativamente quando restarem menos de 60 segundos e mantenha o token anterior em cache como fallback — nunca busque um token novo a cada requisição, e uma falha de renovação não deve bloquear a operação.

Parâmetros

Parâmetro	Tipo	Descrição
`CLIENT_ID`Obrigatório	string	Identificador do cliente OAuth.
`CLIENT_SECRET`Obrigatório	string	Segredo do cliente OAuth.

Endpoints de token

Valor	URL	Descrição
`PROD`	https://<AUTH_PROD_HOST>/realms/ingresse/protocol/openid-connect/token	Host fornecido junto com suas credenciais no onboarding.
`DEV`	https://auth.dev.ingresse.com/realms/ingresse/protocol/openid-connect/token

Cabeçalhos por interface

Interface	Cabeçalhos
Partner Reports	Authorization: Bearer {access_token} Content-Type: application/json Token de usuário com claims email e sub (UUID) — ver aviso acima.
Access Control	Authorization: Bearer {access_token} Accept: application/json

Permissão adicional na Partner Reports

Além do token, o parceiro precisa da permissão events.reports concedida na organização e em cada evento consultado. A própria API valida a cada requisição e retorna 403 ACL_FORBIDDEN quando ausente. A concessão é feita pela equipe de integrações no onboarding.

Formatos e erros

Veja formatos, paginação e códigos de erro comuns em Convenções da API.