Solicitação de acesso

Rascunho para revisão

Este conteúdo é um rascunho e está sujeito a revisão antes da publicação.

Visão geral

Ao final do processo, o parceiro recebe as credenciais e as chaves para as APIs contratadas e passa a obter tokens e a chamar essas APIs.

O acesso é concedido por API e por função. Por exemplo, na API Workflow o parceiro pode receber leitura (Workflow.Read), escrita (Workflow.Write) ou ambas; na API Cadastro, leitura (Cadastro.Read). A Oslo concede apenas o necessário para o uso descrito na solicitação (menor privilégio). As funções estão descritas em Autenticação.

O fluxo

1. Solicitação. O parceiro envia o pedido pelo canal oficial da Oslo (canal: a definir).

   Informações a incluir (sugestão, a validar pela Oslo):

   • razão social e CNPJ;
   • contato técnico e contato para incidentes de segurança;
   • APIs e funções desejadas;
   • ambiente (por ora, somente desenvolvimento);
   • finalidade do uso e volume estimado de chamadas.

2. Análise e aprovação. A Oslo analisa o pedido (responsável e prazo: a definir). A aprovação define exatamente quais APIs e funções o parceiro recebe.

3. Provisionamento. A Oslo cria as credenciais do parceiro (client_id e client_secret), com permissão apenas nas APIs e funções aprovadas, e uma chave de assinatura para cada API contratada.

4. Entrega por canal seguro (canal: a definir). O client_secret é entregue uma única vez. O parceiro recebe:

   • o client_id;
   • o client_secret;
   • o scope de cada API contratada;
   • a chave de assinatura de cada API;
   • a URL base.

5. Primeiro acesso, em desenvolvimento. Para validar a integração:

   1. obtenha um token em POST /auth/v1/token (veja Autenticação);
   2. chame uma operação de consulta da API contratada;
   3. confira o header X-Request-Id na resposta e guarde-o: é o identificador a citar no Suporte.

6. Operação contínua.

   • Renove o token pela claim exp, sem assumir uma duração fixa.
   • Para pedir uma nova API ou uma nova função, use o mesmo canal da solicitação.
   • Quando o acesso não for mais necessário, peça a revogação (processo: a definir).

7. Produção. A promoção para outros ambientes além do desenvolvimento é a definir.

Como o acesso aparece na prática

Situação	Resposta
Pedir token para uma API que o parceiro não contratou	400 na rota de token, com error igual a invalid_grant.
client_id ou client_secret incorretos	401 na rota de token, com error igual a invalid_client.
Token válido, mas sem a função exigida pela operação	403, no formato Problem Details.
Chave de assinatura ausente ou inválida	401.

As respostas da rota de token seguem o formato OAuth 2.0, com error e error_description. Veja Erros.

Nota

Para a chave de assinatura ausente ou inválida, o contrato garante apenas o status 401. Não dependa de um formato específico para o corpo dessa resposta.

Boas práticas de segurança

• Guarde o client_secret em um cofre de segredos. Nunca o coloque em código-fonte, repositório, e-mail ou chat.
• Copie o segredo exatamente como foi entregue. Ferramentas de anotação e de formatação podem inserir caracteres (por exemplo, uma barra invertida antes de ~ e _) e invalidá-lo. Se aparecer invalid_client, confira isso primeiro.
• Use um segredo por ambiente e por equipe, sem compartilhar.
• Em caso de vazamento ou suspeita, avise a Oslo imediatamente para revogar o segredo e emitir um novo.
• Trate o token como opaco: não o decodifique nem interprete seu conteúdo.

Pendências a definir pela Oslo (remover antes da publicação)

• Canal de solicitação de acesso.
• Responsável e prazo de aprovação.
• Canal de entrega das credenciais.
• Validade e rotação do client_secret.
• Ambientes além do desenvolvimento.
• SLA.
• Contato de suporte.
• Processo de revogação.