OAuth 2.0 (client credentials)
A API Energy Management utiliza o fluxo OAuth 2.0 client_credentials. Todos os pedidos (excetoGET /health e POST /oauth/token) requerem um
token Bearer:
1. Criar credenciais
Qualquer utilizador da sua organização pode criar credenciais de cliente OAuth no painel RiDERgy: abra A minha conta, vá a OAuth Clients e escolha Criar novo cliente. Primeiro, a RiDERgy tem de ativar a API Energy Management para a sua organização; sem isso, os pedidos falham com403 FEATURE_NOT_ENABLED.
- ID do cliente (
emcl_...): não é secreto. Continua visível no painel. - Segredo do cliente (
emcs_...): mostrado uma única vez, ao criar o cliente. Guarde-o de imediato num gestor de palavras-passe ou cofre de segredos. A RiDERgy não o pode mostrar novamente; se o perder, crie um novo cliente e revogue o antigo. - Escolha apenas os scopes de que a sua integração precisa. Os novos clientes começam só com leitura.
- Um cliente pertence à sua organização, não à pessoa que o criou, por isso continua a funcionar se essa pessoa sair.
- A RiDERgy não emite chaves API. Pedidos com um cabeçalho
x-api-keysão recusados com401; use sempre um token Bearer como descrito abaixo.
Ainda sem acesso ao painel? Enquanto a sua organização é integrada, a
RiDERgy pode emitir um cliente temporário que expira após 7 dias. Receberá
o ID do cliente e o segredo por dois canais separados. Assim que tiver acesso
ao painel, crie o seu próprio cliente e peça à RiDERgy para revogar o temporário.
2. Obter um token de acesso
Authorization: Basic base64(client_id:client_secret)
com grant_type=client_credentials no corpo (RFC 6749).
3. Utilizar o token
Passe o token comoAuthorization: Bearer <token> em cada pedido:
- O seu tenant está incorporado no token e não pode ser falsificado — as credenciais de um tenant não podem aceder aos dados de outro.
- Um token expirado ou inválido devolve
401 UNAUTHORIZED. - Um token sem o scope necessário devolve
403 INSUFFICIENT_SCOPE.
Scopes
Os tokens contêm scopes que controlam quais endpoints são acessíveis:
Pedidos a endpoints que requerem um scope que o token não possui falharão com
403 INSUFFICIENT_SCOPE.
Testar na documentação
- Abra Obter um token de acesso e clique em Try it.
- Introduza o
client_ide oclient_secret, mantenhagrant_typecomoclient_credentialse envie o pedido. - Copie o
access_tokenda resposta. - Abra qualquer página de endpoint da Referência da API, cole o token no campo Authorization e envie o pedido.
POST/PUT altera limites de
carregamento reais, por isso teste com um cliente só de leitura se não quiser
aplicar alterações.
Rodar e revogar credenciais
- Rodar: crie um novo cliente, mude a sua integração para ele e depois revogue o antigo.
- Revogar: no painel, junto ao cliente. A revogação é imediata: os tokens já emitidos para esse cliente deixam de funcionar no pedido seguinte.
- Os clientes temporários expirados deixam de funcionar da mesma forma.

