Saltar para o conteúdo principal

OAuth 2.0 (client credentials)

A API Energy Management utiliza o fluxo OAuth 2.0 client_credentials. Todos os pedidos (exceto GET /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 com 403 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-key são recusados com 401; 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

Os tokens expiram após 3600 segundos (1 hora). Solicite um novo token antes de o atual expirar. Também pode enviar as credenciais via Authorization: Basic base64(client_id:client_secret) com grant_type=client_credentials no corpo (RFC 6749).

3. Utilizar o token

Passe o token como Authorization: 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

  1. Abra Obter um token de acesso e clique em Try it.
  2. Introduza o client_id e o client_secret, mantenha grant_type como client_credentials e envie o pedido.
  3. Copie o access_token da resposta.
  4. Abra qualquer página de endpoint da Referência da API, cole o token no campo Authorization e envie o pedido.
Os pedidos feitos na documentação vão para a API de produção e só chegam às localizações da sua organização. Um 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.