A API Dinie usa OAuth2 Client Credentials para autenticação. Você troca suas credenciais de API por um access token de curta duração e inclui esse token em todas as requisições.

1. Seu servidor envia as credenciais para POST /v3/auth/token
2. A Dinie retorna um access token JWT de curta duração
3. Inclua o token como header Bearer em todas as requisições subsequentes

Envie uma requisição POST com seu client_id e client_secret via HTTP Basic Authentication:

import Dinie from "dinie";

// O SDK troca as credenciais e faz cache do token automaticamente.
const dinie = new Dinie({
  clientId: process.env.DINIE_CLIENT_ID,
  clientSecret: process.env.DINIE_CLIENT_SECRET,
  environment: "sandbox",
});

{
  "access_token": "dinie_at_...",
  "token_type": "bearer",
  "expires_in": 3600
}

Inclua o token no header Authorization de cada requisição à API:

Authorization: Bearer dinie_at_...

Warning: Nunca inclua credenciais ou tokens em URLs ou parâmetros de query. Sempre use o header Authorization.

Os tokens expiram após 1 hora (3600 segundos). Quando um token expira, a API retorna um erro 401:

{
  "type": "https://docs.dinie.com/errors/authentication-failed",
  "title": "Authentication Failed",
  "status": 401,
  "detail": "Bearer token has expired.",
  "code": "token_expired"
}

Para lidar com a expiração:

1. Renovação proativa -- acompanhe o expires_in e solicite um novo token antes de expirar (ex.: a 80% do TTL)
2. Renovação reativa -- capture respostas 401 com código token_expired, solicite um novo token e reenvie a requisição

Tip: Os SDKs gerenciam a renovação de token automaticamente. Eles solicitam um novo token antes que o atual expire e reenviam requisições que falharam de forma transparente.

Quando você inicializa o SDK com suas credenciais, ele gerencia todo o ciclo de vida do token:

• Troca as credenciais por um token na primeira chamada à API
• Armazena o token em cache na memória
• Renova o token antes da expiração
• Reenvia requisições que falharam devido a tokens expirados

Você nunca precisa chamar o endpoint de token diretamente ao usar um SDK.

1. Armazene secrets com segurança -- use variáveis de ambiente ou um gerenciador de secrets. Nunca faça commit de credenciais no controle de versão.
2. Use apenas chamadas server-side -- nunca exponha seu client_secret em código frontend, aplicativos mobile ou JavaScript client-side.
3. Rotacione credenciais regularmente -- crie uma nova credencial, atualize sua integração e depois revogue a antiga. Veja a seção Gerenciamento de Credenciais abaixo.
4. Separe credenciais por ambiente -- use credenciais diferentes para sandbox e produção.
5. Monitore o uso -- verifique o campo last_used_at nas suas credenciais para detectar uso não autorizado.

Parceiros podem ter múltiplas credenciais de API ativas simultaneamente. Isso permite rotação de credenciais sem downtime -- crie uma nova credencial, atualize sua integração e depois revogue a antiga.

Crie uma nova API key com um nome legível e uma data de expiração opcional.

const credential = await dinie.auth.credentials.create({
  name: "Production Key",
  expires_at: 1804118400,
});

// Armazene credential.client_secret com segurança -- ele é exibido apenas uma vez.
console.log(credential.client_id);
console.log(credential.client_secret);

{
  "id": "dinie_ci_550e8400e29b41d4a716446655440000",
  "client_id": "dinie_ci_550e8400e29b41d4a716446655440000",
  "client_secret": "dinie_cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "Production Key",
  "status": "active",
  "expires_at": 1804118400,
  "created_at": 1709546400,
  "updated_at": 1709546400,
  "last_used_at": null
}

Warning: O client_secret é retornado apenas uma vez no momento da criação. Armazene-o imediatamente no seu gerenciador de secrets. Ele não pode ser recuperado novamente.

Recupere todas as credenciais da sua conta. Os secrets nunca são incluídos nas respostas de listagem.

const credentials = await dinie.auth.credentials.list();

for (const cred of credentials.data) {
  console.log(cred.name, cred.status, cred.last_used_at);
}

{
  "data": [
    {
      "id": "dinie_ci_550e8400e29b41d4a716446655440000",
      "client_id": "dinie_ci_550e8400e29b41d4a716446655440000",
      "name": "Production Key",
      "status": "active",
      "expires_at": 1804118400,
      "created_at": 1709287200,
      "updated_at": 1709287200,
      "last_used_at": 1709544600
    }
  ],
  "has_more": false
}

Revogue uma credencial pelo client_id. A revogação tem efeito imediato -- nenhum novo token pode ser emitido com essa credencial. Tokens já emitidos continuam funcionando até expirarem (até 1 hora).

await dinie.auth.credentials.del("dinie_ci_550e8400e29b41d4a716446655440000");

A resposta é 204 No Content com corpo vazio.

Info: Você não pode revogar sua última credencial ativa. Um parceiro deve sempre ter pelo menos uma credencial ativa. Tentar revogar a última retorna um 409 Conflict com código last_active_credential.

Siga este processo para rotação de credenciais sem downtime:

1. Crie uma nova credencial com POST /v3/auth/credentials
2. Atualize sua integração para usar o novo client_id e client_secret
3. Verifique se a nova credencial funciona solicitando um token com POST /v3/auth/token
4. Revogue a credencial antiga com DELETE /v3/auth/credentials/{old_client_id}

Durante os passos 1--4, todas as credenciais ativas funcionam simultaneamente. Não há downtime na autenticação.

Tip: Defina um expires_at nas credenciais como rede de segurança. Mesmo que você esqueça de revogar uma credencial antiga, ela vai parar de funcionar após a data de expiração.

Monitore o campo last_used_at para detectar credenciais que não estão mais em uso e devem ser revogadas.