Introdução

Para entregar esses benefícios ao consumidor, o Open Insurance operacionaliza e padroniza o compartilhamento de dados e serviços por meio de abertura e integração de sistemas, com privacidade e segurança.

Notificações

Boletim OPIN

Este material tem como objetivo reunir os principais temas e informações referentes ao projeto. Caso tenha alguma dúvida ou sugestão, ou queira entrar em contato com a nossa equipe, o canal de comunicação oficial é o Service Desk.

Boletim OPIN #B22-001

Diretório: Cadastro de APIs Fase 2 (prazo 01/09/2022) e Nova Interface do Usuário
Implantação de melhorias às APIs da Fase 1 (prazo de homologação 28/10/2022)
Certificados de Segurança Padronização e Orientações (prazo estendido)

Boletim OPIN #B22-002

Nova versão das APIs: Dados Cadastrais e Patrimonial Residencial
Testes estruturais e funcionais da Fase 2
Lembrete: Implantação de melhorias às APIs da Fase 1 (28/10/2022)

Boletim OPIN #B22-003

Orientação sobre os testes estruturais do motor de conformidade Fase 2
Requisitos de Segurança
Implantação de melhorias às APIs da Fase 1

Boletim OPIN #B22-004

Atualização de Grandes Riscos e Dados Embarcados de Auto
Atualização de APIs no portal do desenvolvedor
Requisitos de Segurança
Prorrogação da Implantação de melhorias às APIs da Fase 1

Comunicados Open Insurance

Confira as últimas atualizações do Open Insurance Brasil.

Manuais para participantes

Passo a passo para cadastro de Endpoint’s - dados públicos Fase 1
Passo a passo de cadastro no diretório
Passo a passo Cadastro Contatos Técnicos Diretório
Passo a passo testes de confomidade APIs
Orientação de homologação de API
Recomendações Cadastro APIs Diretório
Passo a passo de cadastro no diretório (Ambiente de SandBox)
Criando uma Declaração de Software
Gerando o Certificado BRCAC
Gerando o Certificado BRSEAL
Obtendo um token para acesso as APIs do Diretório
Processo de Segurança
Guia de Experiência de Usuário

Certificação de conformidade

O Test Plan da Fase 2 Versão 2 de dados transacionais é uma série de test plans que foram construídos para testar se as implementaçãos de cada instituição estão em linha com a última versão das APIs de dados transacionais da fase 2 do Open Insurance Brasil, e também estão em linha dos requisitos funcionais esperados

Os testes são divididos em duas diferentes classes:

- Testes Estruturais - Testes que validarão a estrutura do JSON structure para as respostas 20X de cada endpoint de dados. Já que a camada de segurança não será testada, o payload não deve ser protegido via MTLS. Haverão um módulo de teste por API dentro do mesmo test plan.

- Teste Funcionais - Testes que validarão o comportamente funcional da API, com um test plan específico para cada API.

Como os testes estão em desenvolvimento contínuo, até que as certificações iniciem podem ser encontrados erros durante as execuções pelas instituições. Estes erros podem ser relacionados a especificações incertas ou porque o teste está executando um comportamento que não está em linha com o definido nas especificacões. Em ambos os casos, as instituições devem abrir um ticket de issue no GitLab para que o erro possa ser avaliado pelo time de engenharia da Conformance Suite.

Datas das releases

15/09/22 - Testes Funcionais e Estruturais foram disponibilizados em uma versão Alpha, para as seguintes APIs:
- API de Consents, baseados na versão 1.0.0
- API de Resources, baseados na versão 1.0.0
- API de Customers, baseados na versão 1.1.0
- API de Patrimonial, baseados na versão 1.1.0

Requisitos de amostra de dados

Todos os testes necessitam que as instituições provisionem pelo menos um cliente Pessoa Física ou Pessoa Jurídica com o produto que está sendo testado. O CPF ou par de CPF/CNPJ do cliente testado deve ser provisionado na configuração do teste para que as APIs possam ser acessadas e o payload de resposta possa ser validado no escopo do teste.

Quando dados além dos definidos acima forem necessários, o sumário do teste definirá o que deve ser provisionado para que o teste execute com sucesso. Os seguintes test plans contém módulos que necessitam de amostras de dados:

Resources API Test 1.1.0 - entre 3 a 25 recursos acessíveis devem ser provisionados para que o usuário passe no teste de paginação que requer o acesso a uma segunda página.

Execução dos test plans

To execute the tests the user will have to follow a three-step process: Para executar os testes, o usuário deve seguir um processo de 4 passos:

Acessar o Open Insurance Conformance Suite
Selecionar um Test Plan
Preencher os campos de configuração
Executar os módulos de teste

O detalhe de cada passo é definido a seguir:

Acesso a Conformance Suite

The Customer Data tests are available on the Open Insurance Brasil Conformance Suite. To access the conformance suite, the user must have an active account at the Open Insurance Brasil Sandbox Directory.

Os testes de dados transacionais estão disponíveis na Open Insurance Brasil Conformance Suite. Para acessar a Conformance Suite, o usuário deve ter uma conta ativa no Diretório de Sandbox do Open Insurance Brasil.

Após o acesso o usuário será direcionado a uma página inicial com 6 botões:

buttons

Para executar os testes, o usuário deve clicar no botão "Create a new test plan". O usuário pode também verificar logs de testes ou planos publicados nas outras opções.

Selecionar um Test Plan

Ao criar um test plan, o usuário deverá prencher as informações pertinentes a execução:

test info

A lista completa de test plans é disponibilizada no menu "Test Plans". Nele o usuário pode selecionar qualquer um dos testes apresentados na lista. Tanto os testes Estruturais quanto os Funcionais estarão disponíveis nesta lista:

test plans

Após selecionar um test plan, o usuário também será solicitado a preencher três opções:

Client Autenthication Type - Como o cliente se autenticará no servidor para obter o token. FAPI suporta somente private_key_jwt e tls_client_auth dos Métodos de Autenticação OAuth 2.0 disponíveis
Request Object Method - Se PAR será ou não utilizado
FAPI Response Mode - O Open Insurance Brazil não permite JARM, então testes devem ser sempre executados com "plain response"

Preencher os campos de configuração

Dependendo do tipo de teste a ser executado (Funcional ou Estrutural) o usuário será solicitado a providenciar informações adicionais para prosseguir com a execução do teste. As informações são detalhes tanto sobre o cliente que será utilizado pela Conformance Suite, quanto detalhes sobre o servidor que será certificado pelos testes

Configuração dos testes estruturais

O usuário deve providenciar as seguintes informações para executar os testes estruturais:

structural configuration

Test Information:

Estes campos são usados para definir informações gerais utilizadas pela Conformance Suite quando executando e salvando os testes.

alias: Este campo será utilizado para criar o redirect_uri que será utilizado ao executar o fluxo de autorização no escopo dos testes. Este é um campo padrão, e não será utilizado nos testes estruturais.

description: Campo de texto livre que será utilizado para identificar este teste posteriormente.

publish: Selecione se os resultados dos testes devem ser publicados ou mantidos privados - Caso sejam publicados será possível que outros usuários acessem seus test plans ao pesquisar por logs de testes públicos.

Resource:

resourceUrl: Providencie um URL que será utilizado para acessar o endpoint via Regex. É importante notar que o URL providenciado neste campo deve ser o que hospede as payloads que serão validadas no teste estrutural, portanto não deve ser protegido via MTLS. Exemplo: https://www.example.dummypayload.com/open-insurance/consents/v1/

Mock Policy ID: Providencie o policyId mockado que será utilizado para acessar os endpoints, quando necessário. O valor também será utilizado como consentId nos testes estruturais de consentimento. O usuário deve providenciar somente o policyID e **não* a URI contendo o policyId*. Exemplo de URI que utilizará este campo: https://www.example.dummypayload.com/open-insurance/insurance-patrimonial/v1/{policyID}/policy-info

Configuração dos testes funcionais

Os testes funcionais requerem informações adicionais que devem ser preenchidas na configuração do teste. As seções que devem ser preenchidas são:

Test Information
Server
- Client
- Resource
- Directory

A descrição de cada campo é detalhada abaixo:

Test Information:

Estes campos são usados para definir informações gerais utilizadas pela Conformance Suite quando executando e salvando os testes.

alias: Este campo será utilizado para criar o redirect_uri que será utilizado ao executar o fluxo de autorização no escopo dos testes. A redirect_uri terá o seguinte formato: "https://web.conformance.directory.openbankingbrasil.org.br/test/a/alias/callback" no qual alias é o valor definido no campo alias. Certifique-se de que este redirect_uri foi adicionado ao software_statement utilizado no DCR.

description: Campo de texto livre que será utilizado para identificar este teste posteriormente.

Server Details

Estes campos são relacionados à configuração do servidor e suas URIs, incluindo tanto as URIs do Authorisation Server as URIs do Resource Server.

discoveryUrl: Providencie a URI de Meta Data do Authorisation Server, também conhecida como o endereço well-known.

Client Details:

Estes detalhes são relacionados ao Software Statement que deve ser criado no ambiente de Sandbox do Open Insurance Brasil e que será utilizado pela Conformance Suite para conectar-se ao servidor que será testado. Antes de gerar os certificados e realizar o DCR para gerar o client_id necessário, certifique-se de que o redirect_uri correto e o papel de DADOS foi adicionado ao Software Statement.

jwks: Providencie as chaves de assinatura utilizadas pelo cliente em um formato JWKS. Nós sugerimos utilizar a PKI do Diretório de Sandbox para gerar estas chaves. Para criar uma chave de assinatura (BRSEAL) na PKI do Diretório de Sandbox, refira-se ao guia de geração do certificado BRSEAL

As chaves geradas seguindos as instruções do diretório serão geradas em um formato que não é JSON. Porém os testes necessitam que as chaves estejam no formato JWKS. Há diversas maneiras de realizar a conversão. Dado que esta chave será publicada durante a execução do teste, é possível utilizar um conversor online para obter o JWKS, com o procedimento a seguir:

Converta o arquivo .key obtido do diretório para RSA com OpenSSL openssl rsa -in server.key -out server_new.key
Converta a chave RSA para JWK em https://8gwifi.org/jwkconvertfunctions.jsp
Antes de adicionar a Private Key na Conformance Suite, certifique-se de o objeto "alg": "PS256" foi adicionado ao jwks, e que o campo "kid" está atualizado com o kid correto do diretório, e que o campo "use" tem o valor "sig".

mtls.cert: Providencie o conteúdo do certificado Public Transport (BRCAC) gerado no Diretório de Sandbox em formato PEM. Aqui você pode abrir o arquivo .pem com um editor de texto comum e colar os conteúdos neste campo. Para criar um certificado BRCAC na PKI do Diretório de Sandbox, refira-se ao guia de geração do certificado BRCAC

mtls.key: Providencie o conteúdo da chave pública em formato .PEM. Similar ao campo mtls.cert, porém aqui deve ser providenciado o conteúdo da chave que foi gerada junto ao .csr.

mtls.ca: Providencie a cadeia de certificados do Diretório de Sandbox, utilizada para assinar todas as chaves emitidas pela PKI de Sandbox. O arquivo é disponibilizado abaixo, cole todo seu conteúdo no campo.

Estes arquivos também são hospedados na PKI do diretório OPIN: Root CA e Issuing CA

client_id: Neste campo, você deve providenciar o client_id que foi gerado ao realizar um DCR contra o servidor a ser testado com as credenciais preenchidas acima.

Certifique-se de que o Software Statemen utilizado foi registrado com o papel de DADOS.

Resouce

consentUrl: Providencie a URI utilizada para acessar a API de Consent de dados transacionais.

brazilCpf: Providencie o CPF do cliente teste criado para o escopo dos testes. Este CPF será utilizado ao criar o ConsentID em cada um dos planos executados pela Conformance Suite.

brazilCnpj: Caso a instituição deseje testar com um cliente do tipo Pessoa Jurídica, providencie também o CNPJ que será utilizado para criar o Consentimento. Este campo não é obrigatório.

Business or Personal Products: Selecione se a Conformance Suite utilizará as permissões de Customer Personal Permissions (Pessoas Físicas) ou Business Personal Permission (Pessoa Jurídica) ao obter dados do servidor. Caso o campo brazilCnpj seja preenchido, selecione Business Personal Permission.

Executar os módulos de teste

Após a criação dos test plans, você será redirecionado à página de test plan. Para começar a execução dos testes, selecione o módulo de teste a ser executado, e clique em "Run test":

run test

Por favor leia a descrição do teste na caixa de texto azul claro próxima ao topo dos logs da página - essa seção pode conter instruções específicas ao teste; por exemplo, um teste requer que o usuário rejeite o processo de autenticação. Se aplicável, o teste pode pedir que seja aceito (ou negado, ou ignorado) o pedido no dispositivo de autenticação em questão.

Quando o teste for completado, pressione “Continue Plan” para iniciar o próximo teste, ou “Return to Plan” para visualizar seu progresso.

Se você necessitar de suporte, por favor crie um issue no GitLab da Conformance Suite, visitando este link.

Caso seja relacionado a falha de um teste, por favor inclua um link para o log-detail.html relacionado, ou caso esteja utilizando uma instalação local, o arquivo de log baixado.

Lista de Test Plans

26 módulos de testes distintos já foram disponibilizados para a Certificação da Versão das APIs da Fase 2. Estes testes estão separados em seis diferentes test plans, um para cada teste Funcional mais um para os testes Estruturais. Os módulos disponíveis estão listados a seguir: - Functional tests for Consents API - version 1.0.0 - opin-preflight-check-test - opin-consent-api-test - opin-consent-api-status-test - opin-consent-api-test-negative - opin-consent-api-test-permission-groups - opin-consent-api-test-client-limits - opin-consent-api-status-declined-test - opin-consent-api-expired-consent-test - opin-consents-api-delete-test - opin-consent-inavlid-user-test - Functional tests for Resources API - version 1.0.0 - opin-resources-api-test - opin-resources-api-test-404-customer-data - opin-resources-api-pagination-test - Functional tests for Customer Personal API - version 1.1.0 - opin-customer-personal-data-api-test - opin-customer-personal-api-wrong-permissions-test - Functional tests for Customer Business API - version 1.1.0 - opin-customer-business-data-api-test - opin-customer-business-api-wrong-permissions-test - Functional tests for Patrimonial API - version 1.1.0 - opin-patrimonial-api-test - opin-patrimonial-api-wrong-permissions-test - opin-patrimonial-resources-api-test - opin-patrimonial-residencial-api-branch-test - Structural tests - opin-consents-api-structural-test - opin-resources-api-structural-test - opin-customer-personal-api-structural-test - opin-customer-business-api-structural-test - opin-patrimonial-api-structural-test

Workshops

1º Workshop Processo de Certificação Funcional das APIs Fase 2 com a Raidiam (23/11/2022)

Calendário

Este anexo tem como objetivo detalhar quando a versão das APIs do Open Insurance é alterada. Ele poderá ser acessado clicando aqui.

Este anexo tem como objetivo detalhar quando a versão das APIs do Open Insurance é alterada, conforme a classificação da modificação.Ele poderá ser acessado clicando aqui.

Major*: Versão gerada para mudanças de legislação e atualização de documentações oficiais que só poderão ser lançadas com a anuência da SUSEP, por exemplo, v1.0.0 e v2.0.0;

Minor: Versão gerada quando forem realizadas atualizações que descompatibilizam o mercado, mas que não se tratam de versões major, por exemplo, v1.1.0 e v1.2.0;

Patch: Versão gerada quando há correção de bug ou alteração da documentação que não impacta ou descompatibiliza a API (v1.1.1).

OBS: A instituição deve obrigatoriamente refazer a certificação das APIs no Diretório de Participantes conforme release de uma versão major, minor ou patch.

Alteração	Versionamento
Adição de obrigatoriedade de campo	minor
Alteração de pattern que impacta a validação
Retirada de campo	minor
Adição de campo	minor
Ajuste na grafia do campo	minor
Alteraçao do tipo do campo	minor
Diminuição de número de caracteres	minor
Atualizações de REGEX para início de validação de campos antes não validados	minor
Atualização de patterns que não impactam a validação	patch
Retirada de obrigatoriedade de campo	patch
Aumento no número de caracteres	patch
Adição de enum	patch
Ajuste na descrição do campo	patch
Alteração nos exemplos do campo	patch
Atualizações de REGEX que não impactam a validação	patch
Alteração de pattern que não impacta a validação	patch
Retirada de campo não obrigatório	patch
Adição de campo não obrigatório	patch
Retirada da obrigatoriedade de um Campo	patch

Padrões

Estes padrões representam a versão 1.0.0, a qual fornece uma visão alto nível dos padrões.

Observe que, nesta proposta, as palavras-chave DEVEM, NÃO DEVEM, NECESSÁRIAS, RECOMENDADO, PODE e OPCIONAL, devem ser interpretadas conforme descrito na RFC2119.

Princípios

Os seguintes princípios técnicos não exaustivos constituem a base para o desenvolvimento e implementação das APIs para o Open Insurance no Brasil.

Princípio 1: Segurança

A adoção de mecanismos de segurança no design e implementação das APIs do Open Insurance no Brasil deverá considerar os padrões aplicáveis a cada uma de suas fases, visando a proteção e a disponibilidade do ecossistema como um todo, considerando clientes, participantes e os dados específicos compartilhados em cada fase.

Princípio 2: RESTful APIs

A API irá aderir aos conceitos de RESTful API sempre que for possível e sensato.

Princípio 3: Padrões existentes

Os padrões existentes serão adotados sempre que sua aplicação for relevante/apropriada e desde que não violem nenhum dos demais princípios, com foco na experiência do desenvolvedor e do usuário, e ainda, prevendo a extensibilidade, resiliência e a evolução do Open Insurance no Brasil.

Princípio 4: ISO 20022

Os payloads das APIs serão desenvolvidos utilizando como base os elementos e componentes de mensagem ISO 20022, que poderão ser modificados, caso necessário, para deixar o payload mais simples e/ou atender às características locais, tal como implementado em diferentes jurisdições.

Princípio 5: Extensibilidade

Os fluxos das APIs serão estendidos para atender a casos de uso mais complexos em futuros releases, e, portanto, esse princípio será mantido em mente durante o design, e os procedimentos serão detalhados durante a implementação.

Princípio 6: Códigos de Status

A API usará dois códigos de status que atendem a dois propósitos diferentes: (i) o HTTP status code reflete o resultado da chamada da API e (ii) um campo status em alguns resource payloads reflete o status dos resources nos casos de acesso write (p.ex. iniciação de pagamento).

Princípio 7: Identificadores únicos

Um recurso REST deverá ter um identificador exclusivo que possa ser usado para identificar o recurso alvo da API. Este identificador será usado para criar URLs que permitam endereçar recursos específicos, obedecendo aos padrões definidos nesta documentação, no item Formação e estabilidade do ID.

Princípio 8: Categorização dos requisitos de implementação

Quando um requisito estiver sendo implementado por um transmissor e/ou um receptor, uma categorização diferente será aplicada. As funcionalidades, endpoints e campos em cada recurso serão categorizados como 'Obrigatório', 'Condicional' ou 'Opcional'.

Princípio 9: Agnósticas

As APIs serão agnósticas à implementação onde elas poderão ser consumidas independente das tecnologias adotadas no ecossistema, porém com aderência aos princípios contidos nesta documentação.

Princípio 10: Idempotência

As APIs serão definidas como idempotentes para não causar uma experiência ruim ao consumidor ou aumentar os indicadores de risco falso positivo. Trata-se de recurso necessário para garantir que não haja duplicidade em caso de perda de comunicação e não deve se limitar aos verbos HTTP, devendo ser aplicado ao design completo da API.

Versionamento

Os padrões de versionamento das APIs do Open Insurance Brasil estão dispostos na seção Calendário

Estrutura da URI

A estrutura da URI para os endpoints deve ser implementada conforme abaixo:
<host> / open-insurance / <api> / <versão> / <recurso>

Os componentes desta estrutura de URI estão descritos abaixo:

Host: O host de API da seguradora implementadora é um endereço base definido pela entidade transmissora de dados.
“open-insurance”: Esta é uma string constante que representa a finalidade desta API.
API: A API que será consumida (p.ex. channels).
Versão: O número da versão da API. Na URI a versão deve ser precedida pela letra "v" seguida pelo número da versão a ser consumida (p.ex. v1, v2, v25).
Recurso: O recurso a ser consumido dentro de uma API. Utilizando como exemplo a API channels, a mesma possui 5 recursos:
- branches
- electronic-channels
- phone-channels

A versão minor será repassada apenas no header do payload de resposta, orientando a instituição receptora sobre quais serão os dados no retorno.

Como exemplo, para realizar o consumo do método electronic-channels da API channels na versão 1, a URI ficaria com a seguinte estrutura:

<host>/open-insurance/channels/v1/electronic-channels

Cabeçalhos HTTP

Cabeçalhos HTTP suportados e suas funções.

Cabeçalho de requisição

Nome do cabeçalho	Descrição	Obrigatório
Content-Type	Representa o formato do payload de requisição, por padrão/default definido como application/json;charset UTF-8. Obrigatório para chamadas PUT e POST. Os transmissores poderão implementar tratamento para outros padrões, sendo obrigatório apenas o suporte ao padrão.	Não
Accept	Especifica o tipo de resposta. Se especificado, deve ser definido como `application/json`, a menos que o endpoint explicitamente suporte outro formato. Se for definido um valor não suportado pelo endpoint, será retornado o código HTTP 406. Se não especificado, o padrão será `application/json`.	Não
Accept-Encoding	Especifica os tipos de encoding(geralmente algoritmo de compressão) que são suportados pelo cliente, com previsão de suporte ao gzip por parte dos transmissores, sendo que o padrão é a transmissão dos dados não compactados e esta orientação aplica-se aos Dados Abertos.	Não
If-Modified-Since	Condiciona o resultado da requisição para que o recurso só seja enviado caso tenha sido atualizado após a data fornecida. Utiliza o padrão da RFC 7232, sessão 3.3: If-Modified-Since do protocolo HTTP.	Não
x-fapi-auth-date	Data em que o usuário logou pela última vez com o receptor	Condicional
x-fapi-customer-ip-address	O endereço IP do usuário se estiver atualmente logado com o receptor	Condicional
x-fapi-interaction-id	Um UUID RFC4122 usado como um ID de correlação. Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta	Não
Authorization	Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado	Sim
x-idempotency-key	Cabeçalho HTTP personalizado. Identificador de solicitação exclusivo para suportar a idempotência	Condicional
x-customer-user-agent	Indica o user agent que o usuário utiliza	Condicional

Cabeçalho de resposta

Nome do cabeçalho	Descrição	Obrigatório
Content-Encoding	Cabeçalho que indica o tipo de encoding (geralmente algoritmo de compressão) que foi utilizado para envio da resposta.	Não
Content-Type	Representa o formato do payload de resposta. Deverá ser `application/json` a menos que o endpoint requisitado suporte outro formato e este formato tenha sido solicitado através do cabeçalho `Accept` no momento da requisição.	Sim
x-v	Cabeçalho que indica a versão implementada da API pela instituição transmissora. Deve ser preenchido de forma completa, por exemplo: `x-v : 1.0.2`	Sim
Retry-After	Cabeçalho que indica o tempo (em segundos) que o cliente deverá aguardar para realizar uma nova tentativa de chamada. Este cabeçalho deverá estar presente quando o código HTTP de retorno for `429 Too many requests`	Não
Last-Modified	Informa a data e hora em que o recurso foi modificado pela última vez. Utiliza o padrão da RFC 7232, sessão 2.2: Last-Modified do protocolo HTTP.	Não
x-fapi-interaction-id	Um UUID RFC4122 usado como um ID de correlação. O transmissor deve usar o mesmo valor recebido na requisição para o cabeçalho de resposta recebido na requisição, caso não tenha sido fornecido, deve se usar um UUID RFC4122	Não
x-rate-limit	Indica o limite de requisições na API no tempo	Condicional
x-rate-limit-remaining	Indica o número de requisições restantes	Condicional
x-rate-limit-time	Informa o tempo do limite ou tempo para reset desse limite	Condicional

Códigos de resposta HTTP

Os códigos de resposta HTTP devem ser utilizados conforme tabela mais abaixo. Observação: com a implementação do cadastro por endpoint no diretório de participantes e conforme orientação do regulador, as instituições participantes NÃO DEVEM cadastrar endpoints de produtos ou serviços que não ofertem. Neste caso específico - a consulta em um endpoint não cadastrado - o status code esperado na resposta é o 404 - NOT FOUND.

Códigos

Situação	Código HTTP	Notas	POST	GET	DELETE
Consulta concluída com sucesso.	200 OK.	No caso de POST, retornar 200 apenas quando não acarretar alteração de recurso	Sim	Sim	Não
Execução normal. A solicitação foi bem sucedida.	201 Created.	A operação resulta na criação de um novo recurso.	Sim	Não	Não
Operação de exclusão concluída com sucesso.	204 No Content.		Não	Não	Sim
A resposta não foi modificada desde a última chamada	304 Not Modified		Não	Sim	Não
A requisição foi malformada, omitindo atributos obrigatórios, seja no payload ou através de atributos na URL.	400 Bad Request.	A operação solicitada não será realizada.	Sim	Sim	Sim
Cabeçalho de autenticação ausente/inválido ou token inválido.	401 Unauthorized.	A operação foi recusada devido a um problema de autenticação.	Sim	Sim	Sim
O token tem escopo incorreto ou uma política de segurança foi violada.	403 Forbidden.	A operação foi recusada devido a falta de permissão para execução.	Sim	Sim	Sim
O recurso solicitado não existe ou não foi implementado.	404 Not Found.		Sim	Sim	Sim
O consumidor tentou acessar o recurso com um método não suportado.	405 Method Not Allowed.		Sim	Sim	Sim
A solicitação continha um cabeçalho Accept diferente dos tipos de mídia permitidos ou um conjunto de caracteres diferente de UTF-8.	406 Not Acceptable.		Sim	Sim	Sim
Indica que o recurso não está mais disponível.	410 Gone.		Sim	Sim	Sim
A operação foi recusada porque o payload está em um formato não suportado pelo endpoint.	415 Unsupported Media Type.		Sim	Não	Não
A solicitação foi bem formada, mas não pôde ser processada devido à lógica de negócios específica da solicitação.	422 Unprocessable Entity.	Se aplicável ao endpoint, espera-se que esse erro resulte em um payload de erro.	Sim	Sim	Não
A operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite global de requisições concorrentes foi atingido.	429 Too Many Requests.	A limitação é um requisito não funcional. O titular dos dados deve incluir o cabeçalho `Retry-After` na resposta indicando quanto tempo o consumidor deve esperar antes de tentar novamente a operação.	Sim	Sim	Sim
Ocorreu um erro no gateway da API ou no microsserviço.	500 Internal Server Error.	A operação falhou.	Sim	Sim	Sim
O serviço está indisponível no momento.	503 Service Unavailable.		Sim	Sim	Sim
O servidor não pôde responder em tempo hábil.	504 Gateway Timeout.	Retornado se ocorreu um tempo limite, mas um reenvio da solicitação original é viável (caso contrário, use 500 Internal Server Error).	Sim	Sim	Sim

Convenções de payload

Esta seção do padrão descreve as estruturas padrões de requisição e resposta para todos os endpoints das APIs, assim como as convenções de nomenclatura para os atributos.

Estrutura de requisição

{
  "data": {
    "..."
  }
}

Cada requisição deve ser um objeto JSON contendo um objeto data para armazenar os dados primários da requisição.

No mesmo nível do objeto data, poderá existir um objeto meta se assim for especificado pelo endpoint. O objeto meta é usado para fornecer informações adicionais ao endpoint, como parâmetros de paginação, contagens de paginação ou outros propósitos complementares ao funcionamento da API.

A definição do conteúdo para o objeto data será definida separadamente para cada endpoint.

Estrutura de resposta

{
  "data": {
    "..."
  },
  "links":{
    "..."
  },
  "meta": {
    "..."
  }
}

Cada endpoint retornará um objeto JSON contendo os atributos abaixo:

Se a resposta for bem-sucedida (200 OK), o objeto JSON irá conter:
- obrigatóriamente um objeto data
- obrigatóriamente um objeto links
- opcionalmente um objeto meta, se necessário pela definição do endpoint requisitado
Se a resposta for malsucedida (não 200 OK), o objeto JSON poderá conter:
- um objeto errors (conforme a definição específica do endpoint)

A definição do conteúdo para os objetos data e meta será definida separadamente para cada endpoint.

O objeto links irá conter hypermedia (referências para recursos relacionados) para outros recursos da API requisitada.

O objeto de links sempre irá conter o atributo self que irá apontar para a URI da solicitação atual.

Estrutura de resposta de erros

{
  "errors": [
    {
        "code": "...",
        "title": "...",
        "detail": "..."
    }
  ],
  "meta":{
    "..."
  }
}

O objeto errors será um array de zero ou mais objetos. Os atributos deste objeto serão os descritos abaixo:
- obrigatoriamente o atributo code contendo um código de erro específico do endpoint;
- obrigatoriamente o atributo title contendo um título legível por humanos do erro deste erro específico;
- obrigatoriamente o atributo detail contendo uma descrição legível por humanos deste erro específico;
- opcionalmente o objeto meta contendo dados adicionais sobre o endpoint que seja relevante para o erro.

Convenções de nomenclatura de atributos

Caracteres válidos em nomes de atributos

Todos os nomes de objetos e atributos definidos nos objetos JSON de requisição e resposta devem ser nomeados seguindo o padrão camelCase, tendo seu nome composto apenas por letras (a-z, A-Z) e números (0-9).

Qualquer outro caractere não deve ser usado nos nomes dos objetos e atributos, com exceção do caractere - (hífen), que poderá ser utilizado apenas conforme descrito na seção Extensibilidade.

Estilo de nomeação de atributos

Os nomes dos objetos e atributos devem ser nomes significativos e em língua inglesa. Quando houver diferença entre inglês americano e inglês britânico no termo a ser utilizado, deverá ser utilizado o termo em inglês britânico. P.ex. Utilizar o termo Post Code (Reino Unido) ao invés de Zip Code (Estados Unidos).

Arrays devem ser nomeados no plural. Demais atributos deverão ser nomeados no singular.

Convenções de propriedade dos atributos

Tipos de dados dos atributos

Cada atributo deverá estar associado a um tipo de dado. A lista de tipos de dados válidos está definida na seção tipos de dados comuns. Se um tipo de dado personalizado é necessário para um atributo, o mesmo deverá ser classificado como uma string com uma descrição clara de como o valor da propriedade deve ser interpretado.

Atributos Obrigatórios / Opcionais

Os atributos obrigatórios devem estar presentes e ter um valor não nulo, seja em uma requisição ou resposta, para que payload seja considerado válido.

Os atributos condicionais devem ter uma marcação de restrição vinculada a eles na documentação da API (Swagger), no campo 'description'.

Atributos vazios / nulos

Um atributo omitido (ou seja, um atributo que não está presente no payload) será considerado equivalente a um atributo que esteja presente com o valor null.

Uma string vazia (“”) não será considerada equivalente a null.

O valor booleano false não será considerado equivalente a null. Os atributos booleanos opcionais, por definição, possuirão três valores possíveis: verdadeiro (true), falso (false) e indeterminado (null).

Na situação onde o campo a ser informado no payload seja obrigatório e a Instituição, seja consumidora no envio ou transmissora no retorno, não a possuir, deve-se implementar o valor padronizado: “NA” - Não se Aplica, com exceção dos campos declarados como ENUM que deverão ser sempre preenchidos com os valores válidos para o ENUM correspondente.

Convenções de nomenclatura

Todos os nomes devem ser autoexplicativos, sem redundância de termos e sem ambiguidade de entendimento, além de seguir o padrão Lower Camel Case (primeira letra de cada termo maiúscula, com exceção do primeiro termo, que fica todo em minúsculas e sem espaços ou pontuações entre os termos). Ex: “areaCode”.

Os nomes das estruturas (composição de atributos sobre um assunto) que podem ter mais de uma ocorrência devem sempre estar no plural.

Os nomes dos atributos devem:

Sempre estar no singular
Nos casos em que o nome não ficar claro, devem ser incluídos mais termos para esclarecer o entendimento
Para garantir o entendimento e a padronização, nos casos de atributos que tratem dados específicos, sempre devem ser usados termos complementares no fim dos nomes. São esses:
- nomes = Name (p.ex. ownerName)
- datas = Date (p.ex. openingDate)
- horários = Time (p.ex. openingTime)
- quantidades = Quantity (p.ex. eventLimitQuantity)
- textos explicativos = Info* (p.ex. additionalInfo)
*Para textos explicativos de informações complementares, o nome completo do atributo é “additionalInfo”
Em atributos que sejam indicadores binários (flags), o nome deve estar formatado como pergunta, com um verbo como primeiro termo. Ex: "hasDeductibleOverTotalCompensation"

Tipos de dados comuns

Propriedades (em construção)

Tipo	Descrição	Exemplos válidos
AmountString	- Uma string que representa um valor monetário. - Um número positivo, zero ou negativo. - Sem o símbolo da moeda. - Com pelo menos 1 e no máximo 16 dígitos antes do ponto decimal. - Com no mínimo 2 dígitos (mais dígitos são permitidos, porém não obrigatórios). - Sem formatação adicional. Ex: Separador de milhar.	"1.37" "54.85" "3456928.98" "-2387.02"
Boolean	- Valor booleano padrão.	true false
CurrencyString	- Uma string que representa a abreviação da moeda conforme especificação ISO-4217.	"BRL" "USD" "EUR"
DateTimeString	- Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).	"2020-07-21T08:30:00Z"
DurationString	- Uma string que representa um período de duração conforme especificação ISO-8601.	"P23DT23H" "PT2H30M"
Enum	- Uma string que representa um domínio de valores - Todos os possíveis valores são definidos. - Os valores devem estar em letras maiúsculas. - Espaços em branco devem ser substituídos por _. - Artigos e preposições devem ser removidos. - Não devem possuir caracteres acentuados.	"PRIMEIRA_OPCAO" "OUTRA_OPCAO_EXISTENTE"
Integer	- Números inteiros.	-1 0 1
RateString	- Uma string que representa um valor percentual, tendo como referência que 100% é igual ao valor 1. - Com pelo menos 1 e no máximo 16 dígitos antes do ponto decimal. - Com no máximo 16 dígitos após o ponto decimal. - Sem formatação adicional. Ex: Separador de milhar.	"0.01" "0.1" "-0.05" "-0.98365" "0.1023"
String	- Padrão de texto UTF-8 sem restrição de conteúdo.	"Uma string qualquer."
TimeString	- Uma string que representa a hora conforme especificação RFC-3339,sempre com a utilização de timezone UTC(UTC time format).	"00:39:57Z"
URIString	- Uma string que representa URI válida.	"http://www.google.com.br"
CountryCode	- Código do pais de acordo com o código “alpha3” do ISO-3166.	"BRA"
IbgeCode	- Código IBGE de Município. A Tabela de Códigos de Municípios do IBGE apresenta a lista dos municípios brasileiros associados a um código composto de 7 dígitos, sendo os dois primeiros referentes ao código da Unidade da Federação.	"3550308"
DateString	- Uma string com data conforme especificação RFC-3339	"2014-03-19"

Paginação

Cada recurso de cada API pode possuir ou não paginação, caso a quantidade de registros retornados justifique a mesma. A paginação estará disponível e deverá funcionar independente se o recurso permite filtros por query ou POST. Isso é, filtros e paginação são aplicados de forma independente.

Parâmetros de Requisição

Exemplo de query com paginação

GET {uri}?page=1&page-size=25

Quando existir paginação para o recurso deverão ser utilizados os parâmetros de query abaixo para a navegação dos resultados:

Parâmetro	Descrição	Valor Padrão
page	Número da página que está sendo requisitada (o valor da primeira página é 1).	1
page-size	Quantidade total de registros por páginas.	25

Atributos de Resposta

Exemplo de paginação - Apenas uma página

A paginação das APIs são feitas no objeto principal da API. Por exemplo na API de branches, conforme exemplo abaixo, os registros a serem paginados são os objetos "branches". O mesmo deve ser seguido para as demais APIs, por exemplo, "products" nas APIs de produtos, "resources" na API de resources etc.

{
    "data": {
        "brand": {
            "name": "EXEMPLO",
            "companies": [
                {
                    "name": "SEGURADORA EXEMPLO",
                    "cnpjNumber": "123456",
                    "branches": [
                        {...},
                        {...},
                        {...}
                    ]
                }
            ]
        }
    },
    "links": {
        "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches",
    },
    "meta": {
        "totalRecords": 3,
        "totalPages": 1
    }
}

Exemplo de paginação - Primeira página

{
    "data": {
        "..."
    },
    "links": {
        "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=1&page-size=25",
        "next": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=2&page-size=25",
        "last": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=10&page-size=25"
    },
    "meta": {
        "totalRecords": 250,
        "totalPages": 10
    }
}

Exemplo de paginação - Última Página

{
"data": {
    "..."
},
"links": {
    "self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=10&page-size=25",
    "first": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=1&page-size=25",
    "prev": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=9&page-size=25"
},
"meta": {
    "totalRecords": 250,
    "totalPages": 10
}

Além dos dados requisitados, as respostas paginadas também terão em sua estrutura dois objetos adicionais que incluirão parâmetros para facilitar a navegação das páginas:

Links

Os links devem sempre ser validados de acordo com o pattern publicado no swagger.

Quando preenchidos devem ter a mesma estrutura (schema, host, api, versão e recurso) do que esta sendo paginado.

No objeto links, serão retornadas hypermedia (referências para os recursos relacionados) de paginação conforme parâmetros abaixo:

Parâmetro	Descrição	Restrição
first	A URI para requisitar a primeira página.	Obrigatório se a resposta não for a primeira página.
last	A URI para requisitar a última página.	Obrigatório se a resposta não for a última página.
prev	A URI para requisitar a página anterior.	Obrigatório quando houver página anterior. Não deve ser enviado quando for a primeira página.
next	A URI para requisitar a próxima página.	Obrigatório quando houver página posterior. Não deve ser enviado quando for a última página.

Parâmetro	Descrição	Restrição
totalRecords	O número total de registros da requisição.	Este atributo é obrigatório.
totalPages	O número total de páginas da requisição.	Este atributo é obrigatório. Se não possuir nenhum registro o valor deve ser 0.

Regras Adicionais

O tamanho máximo da página (page-size) é 1000 registros para qualquer endpoint (a menos que na API esteja especificado outros valores).
A instituição transmissora/detentora pode definir um tamanho máximo da página (page-size) inferior ao tamanho máximo permitido pela API, caso entenda necessário diminuir o limite para atender o SLA de resposta.
Caso a instituição transmissora/detentora defina um tamanho máximo de página (page-size) inferior, se for requisitado uma quantidade de registros maior do que seu limite operacional, e desde que o valor esteja de acordo o tamanho máximo permitido pela API, esta deverá responder entregando os dados e utilizando o page-size do seu limite operacional definido.
A instituição transmissora/detentora deve realizar os ajustes de paginação antes de efetivar a consulta:
Ex: Ao solicitar a segunda pagina 1000 registros, para uma instituição que trabalha com max size 800, a transmissora deve retornar os itens de 801 a 1600.
Se for requisitado uma quantidade de registros maior que o suportado pela API, o retorno será o código HTTP status code 422 Unprocessable Entity, indicando que o servidor entendeu a requisição, mas não é possível processá-la conforme foi solicitado.

Formação e Estabilidade do ID

Dentro desses padrões, a serem melhor especificados a partir da Fase 2 do Open Insurance no Brasil, os IDs de recursos são necessários para atender ao seguinte:

O ID de um recurso deve ser especificado no endpoint de uma API apenas para obter detalhes do recurso ou para realizar alterações no mesmo.
Se o ID for especificado nos padrões do Open Insurance, então ele é obrigatório e deverá ser fornecido pela entidade implementadora da API de acordo com o padrão definido.
Se um ID for especificado, o mesmo deverá ser totalmente desconectado de significados com outras entidades. Por exemplo, um ID não deve ser uma combinação de outros campos ou uma string que possa ter conteúdo sensível que possa ser extraído.
Os IDs devem ser únicos, e sua padronização será detalhada a partir da Fase 2 do Open Insurance no Brasil, porém sua unicidade pode estar dentro de um contexto. Por exemplo, um ID de apólice deve ser único, porém apenas dentro do contexto de apólice.
Nos payloads o nome de campo "id" nunca deverá ser utilizado. Cada campo ID deverá ter um nome significativo, dessa forma independentemente de onde o ID for utilizado entre múltiplos endpoints, ele sempre irá se referir ao seu objeto principal. Por exemplo, IDs para apólices deverão ser representados no JSON como "policyId".

Princípios para a formação de IDs (identificadores) de recursos nas APIs

O ID DEVE ser uma string com limitação de 100 caracteres - limite que poderá ser revisitado em caso de necessidade apresentada por quaisquer dos participantes do Open Insurance Brasil e - aderente aos padrões apresentados na seção 2.1 da RFC 2141;
Uma vez que será trafegado nas chamadas de interface, o ID NÃO DEVE conter dados classificados como PII - Personally identifiable information (Informação Pessoalmente Identificável) ou Informação de Identificação Pessoal;
DEVE ser garantida a unicidade do ID dentro do contexto da API assim como a estabilidade do mesmo, sendo a estabilidade condicionada à manutenção das características de identificação natural do recurso em questão. A alteração das características de identificação natural implica na geração de um novo identificador associado ao recurso;
A utilização de meios técnicos razoáveis e disponíveis para a formação do ID é de livre implementação por parte da instituição transmissora dos dados, de forma que apenas a aderência aos princípios elencados nesta documentação é mandatória.

Extensibilidade

Os padrões do Open Insurance podem não cobrir todas as possibilidades de objetos retornados ou APIs que os participantes desejam expor. Os participantes podem ter o desejo de realizar inovações sobre os padrões definidos oferecendo mais dados afim de atender demandas específicas de mercado. É nossa intenção que os padrões definidos não apenas permitam estas extensões como também sirvam como base para futuras alterações na própria definição dos padrões.

No entanto, é importante que um participante que esteja querendo estender as APIs não impeça um consumidor que foi projetado para consumir apenas o endpoint padrão funcione corretamente.

Para atender tanto as demandas de quem deseja estender as APIs (participantes) quanto as demandas de quem irá realizar o consumo (consumidor das APIs), foram definidos os critérios abaixo.

É possível estender os padrões nos seguintes aspectos:

O participante pode oferecer uma API completamente nova que não está coberta nos padrões definidos
O participante pode oferecer novos endpoints em uma API que já foi definida no padrão
O participante pode oferecer campos de entrada e retorno opcionais para um endpoint que já foi definido no padrão

ID dos participantes

Cada participantes terá um ID que representa a sua instituição. Os participantes da atual versão estão listados abaixo:

ALLI - ALLIANZ SEGUROS S.A.
AUST - AUSTRAL SEGURADORA S.A.
BRAS - BRADESCO SEGUROS S.A.
BRCA - BRASILCAP CAPITALIZAÇÃO S.A.
BRPR - BRASILPREV SEGUROS E PREVIDÊNCIA S.A.
BRSE - BRASILSEG COMPANHIA DE SEGUROS
BTGS - BTG PACTUAL SEGUROS S.A.
CAIS - CAIXA SEGURADORA S.A.
CAIV - CAIXA VIDA E PREVIDÊNCIA S.A.
CARD - CARDIF DO BRASIL VIDA E PREVIDÊNCIA S.A.
CHUB - CHUBB SEGUROS BRASIL S.A.
EULE - EULER HERMES SEGUROS S.A.
HDIG - HDI GLOBAL SEGUROS S.A
HDIS - HDI SEGUROS S.A.
ICAT - ICATU SEGUROS S.A
ITAS - ITAU SEGUROS S.A.
LIBE - LIBERTY SEGUROS S.A.
MAPF - MAPFRE SEGUROS GERAIS S.A.
PORT - PORTO SEGURO COMPANHIA DE SEGUROS GERAIS
PRUD - PRUDENTIAL DO BRASIL SEGUROS DE VIDA S.A
SAFR - SAFRA SEGUROS GERAIS S.A.
STDA - SANTANDER AUTO S.A.
STDC - SANTANDER CAPITALIZAÇÃO S.A.
SOMP - SOMPO SEGUROS S.A.
SULA - SUL AMÉRICA SEGUROS DE PESSOAS E PREVIDÊNCIA S.A.
TOKI - TOKIO MARINE SEGURADORA S.A.
TOOS - TOO SEGUROS S.A.
XPVP - XP VIDA E PREVIDÊNCIA S.A.
XS3S - XS3 SEGUROS S.A.
XS4C - XS4 CAPITALIZAÇÃO S.A.
ZURB - ZURICH BRASIL COMPANHIA DE SEGUROS
ZURS - ZURICH SANTANDER BRASIL SEGUROS S.A.

Participantes que desejam estender os padrões devem adicionar seu prefixo para identificar todas as extensões. Campos adicionais no retorno de endpoints existentes ou em novos endpoints devem usar o prefixo do participante. O prefixo deve ser no formato exposto ao lado (4 letras) e não devem haver prefixos duplicados entre os participantes.

Nesta documentação, quando tivermos que nos referir ao prefixo do participante, o termo <PID> será utilizado.

Novas APIs

Quando a extensão for a criação de uma nova API, o participante deve adicionar seu prefixo a URI antes do nome da nova API, conforme exemplo abaixo.

Por exemplo, uma API definida pelo padrão seguirá o seguinte formato: <host> / open-insurance / <api> / <versão> / <recurso>

Uma API estendida por um participante deverá estar no formato abaixo: <host> / open-insurance / <PID> / <api> / <versão> / <recurso>

Para os endpoints definidos dentro da estrutura acima, os atributos dos payloads não precisam conter o prefixo do participante, pois entende-se que todos os recursos da API estendida não conflitam de nenhum modo com as definidas pelo padrão.

Novos endpoints em APIs existentes

Quando o participante desejar adicionar um novo endpoint em uma API já especificada no padrão, o participante deve incluir seu <PID> como prefixo do recurso que será implementado.

Por exemplo, assumindo a existência do endpoint abaixo para consulta dos sinistros de um seguro de automóvel: <host>/open-insurance/insurance-auto/v1/{policyId}/claim

Se o participante deseja adicionar um novo endpoint que resume os sinistros por um período, então este endpoint poderia ser definido como: <host>/open-insurance/insurance-auto/v1/{policyId}/<PID>-claims-movement

Campos de retorno adicionais em um endpoint existente

Quando o participante desejar adicionar um novo campo ao payload de resposta, o atributo deverá receber o prefixo do participante seguido por um hífen <PID>-.

Se um objeto estiver sendo adicionado ao payload de resposta, apenas o nome do objeto precisa receber o prefixo. Qualquer atributo dentro do novo objeto pode ser nomeado normalmente.

Importante:

Campos existentes não devem ser modificados. Isto inclui adicionar novas opções em campos do tipo Enum.
Um campo obrigatório não deve se tornar opcional como resultado de uma extensão.
*Payloads* de requisição também podem ser estendidos, porém o resultado ainda deve respeitar os padrões definidos caso o campo de extensão não tenha sido utilizado (por definição, campos adicionais no *payload* de *request* devem ser opcionais).
Parâmetros de *query* podem ser adicionados desde que seguidas as mesmas premissas de um novo campo no *payload* de requisição (com prefixo, não obrigatório e sem efeitos colaterais caso não seja informado).
Parâmetros por *header* podem ser adicionados desde que seguidas as mesmas premissas de um novo campo no *payload* de requisição. No entanto, seu prefixo deve estar no formato `x--`.
Novos campos devem atender os padrões definidos de nomenclatura e tipos de dados.

Parâmetros query adicionais

Quando for adicionado um novo parâmetro de query a um endpoint existente, o novo parâmetro deve ter o prefixo <PID>-, evitando assim colisões com parâmetros já existentes.

Filtro de Dados

Opcionalmente, a entidade transmissora de dados poderá realizar filtro de dados através de query de entrada, baseado em campos que julgue relevante para a melhor experiência do cliente.
A informação de quais possibilidades estarão disponíveis (query parameter) deverá constar em documentação adicional disponibilizada pela entidade transmissora.

Extensão do versionamento

Como descrito na seção calendário, o versionamento existe apenas no nível das APIs e não no nível dos endpoints, no entanto caso seja necessário realizar versionamento de um endpoint customizado, o participante poderá utilizar o header x-<PID>-v para que o consumidor possa especificar qual versão do endpoint está requisitando.

Requisitos Não Funcionais

Este material tem como principal objetivo apresentar ao usuário quais são os requisitos não funcionais presentes no OPIN (Open Insurance). Assim as sociedades participantes devem observar tais pontos na implementação das APIs relacionadas ao OPIN.

Limites de tráfego

As APIs deverão suportar, no mínimo:

I - 300 requisições por segundo globalmente, ou seja, independente do endereço IP (Internet Protocol) do qual provêm as requisições; e

II - 500 requisições por minuto originadas de um mesmo endereço IP.

As requisições que excederem os limites poderão ser enfileiradas ou recusadas, caso em que deverão ser respondidas com o código de status HTTP 429 (Too Many Requests). Por fim, as requisições que ultrapassarem os limites deverão ser desprezadas no cálculo do tempo de resposta das implementações das APIs.

Desempenho

Deverá ser medido o tempo de resposta de cada requisição, ou seja, o tempo transcorrido entre o recebimento de uma requisição que não ultrapassa os limites de tráfego e o momento em que a requisição é completamente respondida. Adicionalmente, esta medição deverá ser feita de maneira que os tempos medidos sejam os mais próximos possíveis dos tempos de resposta experimentados por quem fez a requisição. Neste contexto, as APIs deverão manter o percentil 95 do tempo de resposta em no máximo:

I - 1000ms, caso sejam classificadas como APIs de alta prioridade;

II - 1500ms, caso sejam classificadas como APIs de média prioridade; e

III - 4000ms, caso sejam APIs administrativas.

Por exemplo, em um dia que uma API da alta prioridade receba 10.000 requisições, o tempo de resposta de pelo menos 9.500 requisições deve ser inferior a 1.000ms.

Disponibilidade

As APIs “Produtos e Serviços”, “Canais de Atendimento” e “Situação do Ambiente” deverão satisfazer requisitos mínimos de disponibilidade. Cada um de seus endpoints deverá estar disponível:

I - 85% do tempo a cada 24 horas; e

II - 95% do tempo a cada 1 mês; e

III - 99,5% do tempo a cada 3 meses.

Há perspectiva de elevação dos requisitos mínimos de disponibilidade das APIs destinadas ao compartilhamento de outros dados e serviços do escopo do Open Insurance, conforme necessidade futura. O Portal do Open Insurance deverá conter uma especificação detalhada de como a disponibilidade de cada endpoint será calculada.

Link para a última versão do manual de APIs

Manual de APIs do Open Insurance

Segurança

Introdução - Segurança

Esta seção tem como finalidade auxiliar na auto avaliação aos cumprimentos dos requisitos de segurança da informação relacionados a autorização e autenticação de APIs e End-Users, emissão de certificados digitais e requisitos para o onboarding no Diretório de participantes para as Instituições participantes do Open Insurance.

As instituições participantes do Open Insurance possuem a obrigação de acompanhar a edição e a revogação de eventuais normas com impacto no tema de forma a estar permanentemente em dia com as determinações legais. Compõem, de forma não exaustiva, o rol de atos normativos cuja observância é essencial pelas instituições participantes do Open Insurance:

Normativa
Resolução CNSP nº 415, de 2021
Circular Susep nº 635, de 2021
Circular Susep nº 638, de 2021
Lei Geral de Proteção de Dados (LGPD – Lei nº 13.709, de 2018)

Estas especificações baseiam-se, referenciam, e complementam, quando aplicável, os seguintes documentos:

Referência
BCP 195/RFC 7525
Owasp API Top 10
Sans Top 25 Software Errors
CWE Top 25 Software Weaknesses
NIST 800-88
DOD 5220.22-M
ICP Brasil - Manual de Condutas Técnicas 7 - Volume I

Além desse guia, foi elaborado um checklist para auxiliar os participantes do Open Insurance a alcançar um nível adequado de Segurança da Informação, esse checklist pode ser baixado em formato Excel a seguir:

Download Autoavaliação dos requisitos de SI - 1.0.xlsx

Visão geral

As APIs de Open Insurance estão dividas em dois escopos:

open-data
customer-data

Segue, a continuação, um overview das camadas de segurança básicas para atender os contextos Open-data:

Camada	Descrição	Explicação
Física	Firewall	Equipamentos e produtos como filtros, proxys e firewalls direcionados ao controle e segurança da rede física.
Transporte	HTTP - TLS 1.2	Protocolo de criptografia que fornece segurança na comunicação sobre a rede física.
Gestão	API Gateway / Manager	Gateway e Manager para gerenciar a publicação da API com controles de throttling, quotas e outros.

Manual de Segurança

A documentação que detalha os controles técnicos de segurança que serão implementados na arquitetura do Open Insurance junto do conjunto padronizado de regras e requisitos para formação do framework de confiança para acesso de recursos protegidos pode ser acessado aqui

Diretrizes Técnicas de Certificação

Para a entrada segura e assertiva no Ecossistema do Open Insurance Brasil, a Estrutura Inicial disponibilizou um conjunto de ferramentas e infraestrutura para suportar o processo de testes e homologação dos produtos e serviços desenvolvidos pelas Instituições Participantes. Foram disponibilizados ambientes que habilitam ao participante:

Realizar testes da camada de segurança de suas aplicações e posterior certificação dessas aplicações, utilizando a estrutura criada e mantida pela Open ID Foundation (“Motor de Conformidade de Segurança”);
Submeter, ainda em tempo de desenvolvimento, suas implementações das APIs do Open Banking a testes automatizados funcionais (“Motor de Conformidade Funcional”).

Lembramos que uma implementação de versão de API do Open Insurance só poderá ser registrada no ambiente produtivo do Diretório caso tenha sido certificada nos testes de segurança e funcionais.

Todos os detalhes para a execução dos testes e obtenção dos certificados podem ser encontrados no material de orientações do Processo de Segurança. Estes materiais estão em processo contínuo de atualização, podendo sofrer alterações. Qualquer dúvida em relação ao processo, fique à vontade para a submissão de tickets através do Service Desk .

Materiais complementares

Certificação de segurança, OP
1. Documentação: https://openid.net/certification/op_submission
2. Termos: https://openid.net/certification/instructions/#:~:text=OpenID%20Certification%20Terms%20and%20Conditions
3. Solicitação: https://openid.atlassian.net/servicedesk/customer/portal/3/group/3/create/10016
4. Abertura de chamados: https://gitlab.com/openid/conformance-suite/-/issues
Certificação de segurança, RP
1. Documentação: https://openid.net/certification/connect_rp_submission/
2. Termos: https://openid.net/certification/instructions/#:~:text=OpenID%20Certification%20Terms%20and%20Conditions
3. Solicitação: https://openid.atlassian.net/servicedesk/customer/portal/3/group/3/create/10016
4. Abertura de chamados: https://gitlab.com/openid/conformance-suite/-/issues

Workshops

Visão Geral do Ecossistema

Em sua essência, o Open Finance Brasil é um ecossistema de compartilhamento de dados onde os clientes de bancos e outras instituições financeiras desejam compartilhar suas informações de conta ou dar permissão para que os pagamentos sejam executados em seu nome com serviços de terceiros e o Open Insurance Brasil utiliza os padrões de segurança do Open Finance Brasil.

Há uma série de funções necessárias para vincular qualquer sistema de identificação, autenticação e autorização, independentemente do setor. Todas essas funções são necessárias, mas várias funções podem ser desempenhadas por cada participante. Em geral, o usuário final (“Subject”), está dando a um sistema (“Client”) uma autorização (“Access Token”) para acessar um recurso protegido mantido pelo provedor (“Resource Server”). Isso exige que o Subject e o Client sejam identificados e autenticados e que a autorização seja confirmada.

As regras exatas e os requisitos legais para cada função em um setor específico formam um framework de confiança ("Trust Framework"). Cada ecossistema requer um conjunto padronizado de regras e requisitos legais que abrangem todas as funções e obrigações das interações acima. A combinação de quem fornece qual(is) função(ões), os níveis aos quais eles devem desempenhar essas funções e os padrões pelos quais essas operações devem ser definidas por um framework de confiança específico do setor.

Diferentes frameworks de confiança terão diferentes opções de implementação, mas um framework de confiança comum é um pré-requisito para transformar um ‘setor’ em um ‘ecossistema’. Um framework de confiança comum reduz significativamente a complexidade e custos, aumenta a escalabilidade e a interoperabilidade dentro do setor, bem como abre opções para o tipo de padronização intersetorial que o Open Insurance Brasil está buscando.

Diferentes implementações podem ser definidas para setores, com diferentes prós / contras e custos associados para diferentes participantes. Cada uma das implementações propostas pode ser usada para qualquer setor se os pré-requisitos corretos estiverem em vigor. A solução certa dependerá do apetite e alinhamento de cada conjunto de participantes.

A implementação de um mecanismo comum para o Open Insurance Brasil exigirá um compromisso com a simetria entre os setores para incluir detalhes específicos do setor nos princípios do framework de confiança.

É necessário fazer escolhas técnicas para garantir que qualquer implementação forneça uma base estrita e consistente para ter credibilidade, mas mantenha a flexibilidade para se adaptar às necessidades futuras. Isso implica padrões de código-fonte aberto amplamente disponíveis, amplamente compreendidos e que foram experimentados e testados. Além de habilitar um gama de parceiros e fornecedores que podem apoiar qualquer construção técnica, o que significa que continuará havendo espaço para desenvolvimento comercial de soluções.

Participantes de um Ecossistema de Compartilhamento de Dados

Nos ecossistemas de Open Insurance voltados para o consumidor que estamos considerando, temos três participantes principais:

O cliente (user)
A instituição transmissora de dados (provider), que oferece serviços de seguros
A instituição receptora de dados (TPP - Third Party Provider), que oferece uma proposta de Open Insurance para o cliente:

Em todos os casos a seguir, assumimos:

Um cliente possui uma conta para um serviço principal ou conjunto de recursos numa instituição transmissora de dados
Uma instituição receptora de dados oferece ao cliente uma proposta habilitada por meio do compartilhamento inteligente de dados
O cliente dá consentimento à instituição receptora de dados para fins de entrega dessa proposta
A instituição transmissora de dados tem a obrigação de salvaguardar os dados do cliente, mas também de compartilhá-los quando instruído.

O ecossistema também possui provedores de serviços de confiança, que são entidades que fornecem garantia técnica a ambas instituições (transmissoras e receptoras) de que todos estão autorizados a participar do ecossistema.

Os padrões técnicos necessários para dar suporte ao framework de confiança devem atender todos os requisitos a seguir:

Identificação de todos os participantes do ecossistema
Autenticação quando exigida de todos os participantes entre si
Confirmação de autorização de todos os participantes em um ecossistema de compartilhamento de dados

Os serviços técnicos necessários para suportar um ecossistema devem habilitar todos os requisitos acima em uma base e modo contínuos, isto é, não apenas em um único ponto de registro.

Princípios de Especificação e Requisitos de Alto Nível

O Open Insurance Brasil adotou os seguintes princípios e requisitos de alto nível no que diz respeito às normas técnicas.

Consentimento
- Os clientes devem estar sempre no controle de quem tem acesso aos seus dados e para quais fins eles estão sendo usados.
Minimização de dados
- Os clientes devem ser capazes de compartilhar apenas os dados de que precisam, pelo tempo que for necessário.
Segurança
- Uma modelagem de ameaças foi produzido avaliando todas as fraquezas potenciais nos processos de comunicação.
- Todos os pontos fracos identificados foram corrigidos.
Identificação
- Todos os participantes devem ter segurança na identificação de todos os atores do ecossistema.
Autenticação
- Todos os participantes devem comunicar as etapas que foram executadas para autenticar cada participante no ecossistema e em que nível isso foi executado.
Integridade e não repúdio
- Todos os participantes devem ser capazes de provar que as mensagens não foram adulteradas e, na verdade, foram enviadas apenas por um participante legítimo.

Além dos requisitos de alto nível, os seguintes princípios também foram adotados.

Não reinventar a roda, se existir uma especificação que seja adequada para o propósito, amplamente adotada e publicamente disponível, deve-se adotá-la.
Envolver-se com outros órgãos de normalização para aprender com experiências anteriores sobre o que funcionou, o que não funcionou, e o que pode ser feito melhor.
Assegurar o amplo suporte da indústria para garantir o máximo de chances de sucesso e, mais importante, a segurança do cliente.
Solicitar feedback com antecedência e com frequência, reconhecer que serão necessárias várias iterações para desenvolver um padrão.
O framework de confiança que sustenta o ecossistema de compartilhamento de dados, que é o Open Insurance Brasil, é um framework técnico que precisa ser flexível o suficiente para permitir que os participantes e o ecossistema inovem, cresçam e se desenvolvam, enquanto permanecem interoperáveis.

Todos os participantes devem ter certeza de que todos os atores do ecossistema estão lidando com seus dados com segurança tempo todo. Isso requer que todos os participantes testem publicamente seus sistemas quanto à conformidade com as especificações e disponibilizem os resultados de seus testes de conformidade para exame público de outros participantes.

Este é um requisito aplicável à instituições participantes transmissoras e receptoras de dados.

Principais Padrões de Segurança

Estrutura de Autorização OAuth 2.0

O ecossistema de compartilhamento de dados definido pelo Brasil consiste em muitos padrões diferentes, todos girando em torno de conceitos, funções e obrigações que foram tecnicamente definidos no OAuth 2.0 Authorization Framework.

A estrutura de autorização OAuth 2.0 permite uma aplicação de terceiros (third-party application) obter acesso limitado a um serviço HTTP, seja em nome do proprietário de recurso (resource owner) por meio da orquestração de uma interação de aprovação entre o proprietário do recurso e o serviço HTTP, ou permitindo a aplicação de terceiros obter acesso em seu próprio nome.

A especificação base OAuth 2.0 não fornece, por si só, informações suficientes para atender a todas as necessidades definidas pelo framework de confiança do Open Insurance Brasil. Mais notavelmente, não possui uma maneira de transmitir informações de identidade do cliente em um formato padronizado de uma instituição transmissora para uma receptora, e os mecanismos de autenticação que foram definidos na especificação original não são seguros o suficiente para atender aos requisitos de uma indústria altamente regulamentada.

OpenID Connect - A Camada de Identidade para a Internet

Este perfil herda todas as obrigações do OAuth 2.0

OpenID Connect é um conjunto de especificações simplificadas que fornecem uma estrutura para interações de identidade por meio de APIs do tipo REST. A implementação mais simples do OpenID Connect permite que clients de todos os tipos, incluindo baseados em navegador, celulares e clients javascript, solicitem e recebam informações sobre identidades e sessões atualmente autenticadas. O conjunto de especificações é extensível, permitindo que os participantes também suportem, opcionalmente, criptografia de dados de identidade, descoberta do OpenID Provider e gerenciamento avançado de sessão, incluindo logout.

O grupo de trabalho OpenID Foundations Connect tem sido o guardião do Padrão de Identidade “de fato” da Internet por muitos anos, trabalhando em várias especificações que se baseiam no framework de autorização OAuth 2.0, adicionando recursos e requisitos de suporte para melhorar a segurança do framework em si.

Open ID Connect Core: é um perfil do OAuth 2.0, o que significa que herda todos os requisitos e obrigações do OAuth 2.0, mas define o conceito de um id_token e introduz novos mecanismos de autenticação.

Open ID Connect Discovery: apresenta o conceito de um documento de descoberta usado por OpenID Connect (OIDC) Providers para anunciar como os clients OAuth 2.0 podem se comunicar com eles e quais recursos e opções o OIDC Provider oferece suporte.

RFC7591: além de definir o processo de registro dinâmico de clients OAuth, esta especificação apresenta o conceito de Software Statement (“Declaração de Software”), que pode ser usada para fornecer informações sobre um client que é atestado por um serviço de terceiros. Outros atributos de metadados também são definidos no OpenID Connect Registration Specification:

Esta especificação define mecanismos para registrar dinamicamente clients OAuth 2.0 com Authorization Servers (servidores de autorização). Pedidos de registro enviam um conjunto de valores de metadados do client desejado para o Authorization Server. As respostas de registro resultantes retornam um client identifier para ser usado no Authorization Server e os valores de metadados registrados para o client. O client pode então usar esta informação de registro para se comunicar com o Authorization Server usando o protocolo OAuth 2.0. Esta especificação também define um conjunto de campos de metadados do client e valores para os clients usarem durante o registro.

RFC7592: Esta especificação define métodos de gerenciamento de dynamic client registration (registros de cliente dinâmico) do OAuth 2.0 para casos de uso em que as propriedades de um client registrado necessitam ser alteradas durante a vida do client.

As especificações acima são especificações básicas cuja leitura obrigatória sustenta o framework de confiança do Open Insurance Brasil. Entretanto, eles ainda são insuficientes para atender a todos os requisitos e princípios descritos anteriormente.

OpenID Financial Grade 1.0: Baseline

Este perfil herda todas as obrigações do OpenID Connect Core

Reconhecendo as ameaças e riscos restantes que não foram tratados pelo OpenID Connect Core, o grupo de trabalho Financial Grade tem como foco criar uma especificação que visa identificar e endereçar os pontos fracos na especificação OpenID Connect, essencialmente criando um perfil para casos de uso que exigem alto nível segurança.

O perfil Baseline foi originalmente planejado para ser mais facilmente implementado por clients e OpenID Providers às custas de alguns elementos de segurança e, como tal, não oferece o mesmo grau de proteção contra violação de solicitação e resposta.

OpenID Financial Grade 1.0: Avançado

Este perfil herda todas as obrigações do OpenID FAPI 1.0: Baseline

O FAPI 1.0: Advanced profile é atual padrão ouro para API Security, fornecendo um framework de especificação que foi usado como ponto de partida para a criação de uma especificação para o Open Insurance Brasil.

Este padrão especifica um perfil de segurança avançado do OAuth que é adequado para ser usado para proteger APIs com alto risco inerente. Os exemplos incluem APIs que dão acesso a dados altamente confidenciais ou que podem ser usados para acionar transações financeiras (por exemplo, início de pagamento). Este padrão especifica os controles contra ataques, como: violação de solicitação de autorização, violação de resposta de autorização, incluindo injeção de código, injeção de estado e phishing de solicitação de token.

FAPI profile

Sobre o uso de JARM

O suporte ao JARM é opcional aos transmissores e detentores de contas (ASPSP) e, portanto, as instituições que optarem pelo uso do JARM devem, no processo de certificação de segurança, atestar também o suporte a outro profile que não considere o uso do padrão JARM, ou seja, deve também se certificar com um dos profiles listados na tabela a seguir.

Perfil da certificação OIDF
BR-OB Adv. OP w/ MTLS
BR-OB Adv. OP w/ Private Key
BR-OB Adv. OP w/ MTLS, PAR
BR-OB Adv. OP w/ Private Key, PAR

Guia do Usuário para Entidades Transmissoras de Dados

1.0 Registrando um Participante

1.1 Visão Geral do Diretório

Os serviços do framework de confiança providos pelo Open Insurance Brasil fornecem todos os serviços de descoberta necessários para que instituiçoes transmissores e receptoras interajam entre si, sem que seja preciso validar individualmente a autenticidade de cada participante.

Um Authorization Server ou AS, conforme definido por RFC 6749 - The OAuth 2.0 Authorization Framework, executa várias funções em um ecossistema de compartilhamento de dados como o Open Insurance Brasil. Antes de prosseguir, certifique-se de que os conceitos de funções e responsabilidades definidos na RFC original sejam bem compreendidos. Além disso, certifique-se de que os conceitos, funções e responsabilidades definidos no OpenID Connect Core e como eles estendem os conceitos definidos no RFC 6749 são igualmente bem compreendidos.

1.2 Registrando um Authorization Server e OpenID Provider

As seguradoras, geralmente grandes seguradoras, não serão uma entidade única do ponto de vista das operações de tecnologia. Eles podem ter marcas, segurança e infraestrutura de TI diferentes para diferentes segmentos de clientes, ou podem ter alguma infraestrutura de TI que ofereça suporte a várias marcas ou segmentos de clientes. Isso significa que o ecossistema técnico precisa ser flexível o suficiente para suportar uma ampla variedade de implantações de infraestrutura de seguradoras, garantindo que os serviços necessários possam ser descobertos por clientes de instituições receptoras que precisam interagir com ele.

Um modelo flexível para anunciar serviços de autenticação / autorização e os recursos protegidos pelo AuthN e AuthZ é suportado pelo Diretório.

Customer Friendly Name - Será exibido aos clientes pelas instituições receptoras, e já deve ser reconhecido pelos clientes da seguradora.
Customer Friendly Logo - Será exibido aos clientes pelos instituições receptoras para auxiliar no reconhecimento da marca.
Description - Isso pode ser exibido aos clientes pelas instituições receptoras para auxiliar no reconhecimento da marca.
Terms of Service - Este é um link para os Termos de Serviço da seguradora, que podem ser incluídos pelas instituições receptoras.
Notification WebHook - Authorization Servers podem registrar um WebHook que receberá atualizações por push sobre as alterações dos participantes, seus softwares ou certificados.
OpenID Well Known Document Uri - Link para o documento de descoberta do Authorization Server.

Uma seguradora pode optar por ter um Authorization Server ou muitos, desde que satisfaça os seguintes requisitos:

Um cliente pode reconhecer o Authorization Server como um local com o qual normalmente faria interação com a sua seguradora.
O Authorization Server pode emitir tokens para os recursos e serviços que um cliente ou insituição receptora está procurando.
O Authorization Server das instituições transmissoras/detentoras de contas que atenda mais de uma marca deve aceitar mais de um cadastro (criação de client_ids) para um mesmo software statement. Caso a solução de Authorization Server não suporte este comportamento, deverá ser adequado para suportar múltiplas marcas e o cadastramento das marcas no diretório deverá sofrer apontamento de acordo com cada marca.

1.3 Registrando Recursos

Depois que uma seguradora registra um Authorization Server, ela precisa anunciar para quais recursos, APIs ou serviços ele pode fornecer autorização.

Auth Id	Auth Customer Friendly Name	Well Known	Resource	Version
1	Seguros Incríveis - Empresas	https://auth.empresas.amazinginsurance.org.br/.well-known/openid-configuration	consents	1
1	Seguros Incríveis - Empresas	https://auth.empresas.amazinginsurance.org.br/.well-known/openid-configuration	customers	1
2	Seguros Incríveis	https://auth.amazinginsurance.org.br/.well-known/openid-configuration	consents	1
2	Seguros Incríveis	https://auth.amazinginsurance.org.br/.well-known/openid-configuration	customers	1
2	Seguros Incríveis	https://auth.amazinginsurance.org.br/.well-known/openid-configuration	insurance-auto	1
2	Seguros Incríveis	https://auth.amazinginsurance.org.br/.well-known/openid-configuration	insurance-auto	2
2	Seguros Incríveis	https://auth.amazinginsurance.org.br/.well-known/openid-configuration	insurance-patrimonial	1

No exemplo acima, a Seguros Incríveis está anunciando dois serviços que devem ser reconhecidos pelos clientes. “Seguros Incríveis - Empresas" e “Seguros Incríveis". Estes podem ou não estar diretamente relacionados a “Marcas”, pois seguradoras diferentes podem precisar anunciar serviços de autenticação diferentes, mesmo dentro de uma submarca.

Além disso, a seguradora anuncia quais recursos cada um dos servidores de autorização está protegendo ou oferecendo. No exemplo acima, a Seguros Incríveis é compatível com a versão 1 e a versão 2 da API de seguros de automóveis, e o “Amazing Insurances” tem dois sistemas separados de consentimento e informações dos clientes de seguros.

Anunciar corretamente quais recursos são oferecidos por cada servidor é importante para atingir a escala prevista pelo Open Insurance Brasil, além de ser fundamental para garantir que os clientes possam identificar sua seguradora facilmente e que as instituições receptoras possam encaminhar os clientes para o Authorization Server correto com base nos recursos protegidos por cada serviço.

2.0 Validando uma Solicitação de Registro de Cliente

Usando o OpenID Connect Discovery e a especificação de Dynamic Client Registration (DCR) do Open Insurance Brasil. Uma instituição receptora pode registrar seu aplicativo em cada um dos Authorization Servers disponíveis no ecossistema.

Guia do Usuário para Instituições Receptores de Dados

1.0 Registrando um Aplicativo

Em um alto nível, as seguintes etapas principais são necessárias para integrar um novo aplicativo no ecossistema Open Insurance Brasil.

Cadastre sua organização no Diretório de Participantes (Interface do Usuário)
Cadastre seu aplicativo no Diretório de Participantes (Interface do Usuário)
Obtenha credenciais para sua aplicação junto à uma autoridade certificadora ICP-Brasi)(fora do escopo deste documento)
Registre suas credenciais para o seu aplicativo no Diretório de Participantes (Interface do Usuário)
Identifique provedores de informações de conta ou serviços de pagamento de interesse dos clientes de seu aplicativo, pesquisando o Diretório de Participantes (API)
Registre seu aplicativo com cada provedor (API)

1.1 Diagrama de Sequência

Registrando um Aplicativo

1.2 Visão Geral do Diretório

O framework de confiança do Open Insurance Brasil fornece todos os serviços de descoberta necessários para que instituições participantes (receptoras e transmissoras de dados, iniciadoras de serviçoes de seguros) interajam entre si sem serem obrigadas a validarem a autenticidade de identidades, autorizações, Apps, APIs ou credenciais para acessos por aplicativos uns dos outros. Além disso, fornece um único registro de todas propostas ao consumidor sendo oferecidas no mercado e um único ambiente de controle para as autoridades regulatórias que concedem permissões para gerenciar participantes dentro do ecossistema.

O framework de confiança não tem visibilidade ou visão das interações que ocorrem entre instituições participantes receptoras ou transmissoras de dados. Ele é projetado para fornecer confiança e garantia de identidade e autorização apenas. Ele não se enquadra no fluxo de comunicação entre um consumidor e um provedor e não tem conhecimento ou visibilidade de quaisquer dados do cliente. Este modelo de framework de confiança é conhecido como confiança transitiva onde duas partes, uma transmissora e uma receptora, concordam em confiar nas declarações e atestados de legitimidade uns dos outros emitidos por um provedor de confiança comum e, em seguida, prossigam comunicando o que quiserem, sem qualquer validação adicional onerosa ou outro tipo de verificação.

1.3 Acessando o Diretório

Este guia do usuário assume que as organizações participantes já passaram pelo processo de iniciação com a Estrutura Inicial do Open Insurance Brasil e já concluíram todas as integrações necessárias, processos de assinatura de contrato e inclusão de administrador individual.

Tela de login do diretório

1.4 Criação de uma Nova Declaração de Software (SSA)

Uma declaração de software descreve um aplicativo inserido naquilo que pode ser considerado a ‘App Store’ do Open Insurance Brasil. Este registro de aplicativo contém todas as informações necessárias para que uma seguradora identifique tecnicamente e interaja com o aplicativo, além de conter todas as informações que auxiliam os clientes que estejam utilizando-o a confirmar sua legitimidade.

Um novo aplicativo ou declaração de software pode ser registrado fazendo logon no Diretório, acessando sua organização, navegando até ‘Declarações de software’, clicando em ‘Declarações de novo software’ e preenchendo o formulário. Lembre-se de que a maioria dessas informações será exibida aos clientes pelas Seguradoras como parte do processo de redirecionamento ou autorização. Como tal, é importante que todas as URIs e descrições sejam relevantes para o público.

Campos de declaração de software

1.4.1 Atribuição de Funções Regulatórias de Software

Em um ecossistema de compartilhamento de dados complexo e diversificado, as funções regulatórias de uma organização podem mudar. Eles podem ser adicionados e revogados. Isso significa que o software adicionado ao Diretório pode receber permissão de ter zero (0) ou mais funções regulatórias. Um administrador pode atribuir a um determinado software todo e qualquer permissões que a organização proprietária do software pode ter.

Se uma organização perder uma função regulatória, todo software com essa função regulatória será revogado do ecossistema, portanto, é muito importante que um aplicativo receba apenas as funções de que realmente precisa para funcionar.

1.5 Criação e Upload de Certificados

1.5.1 Sandbox

O serviço de Diretório do Open Insurance Brasil inclui uma infraestrutura de chave pública que pode ser usada para criar certificados para os aplicativos sendo registrados no ambiente Sandbox. Basta selecionar certificados no menu e seguir as instruções.

O Diretório suporta vários certificados, tipos de chave e um comando e configuração openssl será disponibilizado como um exemplo. Depois de criar a solicitação de assinatura de certificado (Certificate Signing Request - CSR) para um certificado de “Transporte” e “Assinatura”, você pode enviá-los ao diretório para serem validados e transformados em certificados.

Lembre-se de seguir as práticas de gerenciamento de chaves de sua organização para a geração de certificados. Essas credenciais e chaves precisam ser manuseadas com cuidado. Um evento significativo de comprometimento de chave pode levar ao comprometimento dos dados do cliente.

1.5.2 Produção

Os certificados para acesso e assinatura em ambiente de produção devem ser fornecidos pelo ICP Brasil. Os detalhes sobre os certificados e os requisitos para os certificados estão detalhados no Padrão de Certificados Open Insurance Brasil.

1.5.3 O que é um JWT, JWE, JWS e JWK

Quando os certificados são carregados para o Diretório, o framework de confiança os anuncia em JSON Web Key Sets com cada JSON Web Key (JWK) tendo um ‘KID’ ou um Key ID. Os JWKs, além de ter propriedades específicas que descrevem o algoritmo e os conjuntos de criptografia que eles suportam, também anunciam seu “uso”, que pode ser do tipo ‘enc’ para criptografia ou ‘sig’ para assinatura.

Essas chaves ‘sig’ e pares de chaves ‘enc’ são usadas em muitos lugares dentro do ecossistema do Open Insurance Brasil para criptografar ou assinar dados usando os padrões definidos em RFC 7519 JSON Web Token, que deve ser lido em detalhes pelos desenvolvedores.

Tipos de JWT incluem

OpenID Connect Request Objects definidos em Open ID Connect Core
OpenID Connect id_token definido em Open ID Connect Core

Entre muitos outros.

Esses JWTs podem ser criptografados também usando o JSON Web Encryption (JWE). Na maioria dos casos, as chaves que devem ser usadas para validar uma assinatura da Web JSON (JWS) ou a chave que foi usada para criptografar um JWE são geralmente publicadas como uma JSON Web Key em um JSON Web Key Set com a referência à chave que está sendo carregada no campo de cabeçalho ‘kid’ (Key ID).

Exemplo de Request Object JWT assinado

eyJhbGciOiJQUzI1NiIsInR5cCI6Im9hdXRoLWF1dGh6LXJlcStqd3QiLCJraWQiOiJ4U2tpbXRFa2EyUzFrdDBFQUV4MlJmNkZLendHSi1zUzRReHYzN2xiU2l3In0
.
eyJzY29wZSI6Im9wZW5pZCBvcGVuaW5zdXJhbmNlYnJhc2lsOmdyYW50OkdERVJaR1JXby1lT0V5UTdDVWZqZiIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly90cHAubG9jYWxob3N0L2NiIiwiY29kZV9jaGFsbGVuZ2UiOiJTMmZ4QlVMS2lQUDdxTnZrN2Z5WlBUcUwtYWtJYnJXcU96WlpYU3I1VTZjIiwiY29kZV9jaGFsbGVuZ2VfbWV0aG9kIjoiUzI1NiIsInJlc3BvbnNlX21vZGUiOiJmb3JtX3Bvc3QiLCJzdGF0ZSI6IjAzNTE4MTk2NTA1NTM3ZTIxMWRkMDhjZWRiMTI3MTE4NzBhNTZlYTQ4ODg5MjRkNTk4YzRiMDY0MDMwMTA2M2IiLCJub25jZSI6Ijg5ODFjOGE1NjBjMjFjMGY4NzQ2ZTliOTc4YmZjMDA0YjkyNzRmMmJjZjc4NmEzZTE1YWE5NmM4ZGQ1NDk0ZGQiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYXV0aF90aW1lIjp7ImVzc2VudGlhbCI6dHJ1ZX0sIm5hdGlvbmFsX2lkIjp7ImVzc2VudGlhbCI6dHJ1ZX0sImdpdmVuX25hbWUiOnsiZXNzZW50aWFsIjp0cnVlfSwiYWNyIjp7InZhbHVlcyI6WyJ1cm46b3Blbmluc3VyYW5jZWJyYXNpbDp0cnVzdGZyYW1ld29yazpnb2xkIl0sImVzc2VudGlhbCI6dHJ1ZX19LCJ1c2VyaW5mbyI6eyJhdXRoX3RpbWUiOnsiZXNzZW50aWFsIjp0cnVlfSwibmF0aW9uYWxfaWQiOnsiZXNzZW50aWFsIjp0cnVlfSwiZ2l2ZW5fbmFtZSI6eyJlc3NlbnRpYWwiOnRydWV9LCJhY3IiOnsidmFsdWVzIjpbInVybjpvcGVuaW5zdXJhbmNlYnJhc2lsOnRydXN0ZnJhbWV3b3JrOmdvbGQiXSwiZXNzZW50aWFsIjp0cnVlfX19LCJtYXhfYWdlIjozMDAsImlzcyI6ImFDbkJIalpCdkQ2a3UzS1ZCYXNsTCIsImF1ZCI6Imh0dHBzOi8vYXV0aC5sb2NhbGhvc3QiLCJjbGllbnRfaWQiOiJhQ25CSGpaQnZENmt1M0tWQmFzbEwiLCJqdGkiOiJxOF9OU2NKb3F1OG5kcmNYZmo3TlRDVUNTZDZjUEk5ZzVJN3FFeUlLa1NVIiwiaWF0IjoxNjE4NjY0NzM4LCJleHAiOjE2MTg2NjUwMzgsIm5iZiI6MTYxODY2NDczOH0
.
I-75Ev8Swlk3AXEXevFEyV3FVA40VjjIJQu3sImcVGrxdA3qFzw-gxIMCEHamC94TktI_mv6jebwJa_WCfpTipRdnuT_6f24hjTHCDb261t_uWSu3xZgiJrXvmxtQKykLKe6AVheIfldDPszu3bUmUeg9J3ZF6ilDGcCkphmMXLIPpEFkesOQpkw45mCXuhKLfoCnznax7bN6nlD-cHH0Cd0e2XExy3rmSUJ4CljLkpiJ-aK53WDJDocX2mkcFohRJ6zJOHUWZphZ89qpYCq-8jnCOV-YblG9P4KkzUH7EfdVchVzp8V5FlOfmXZhB2pS5REHBjfsmXrdBChlF4Tig

O exemplo acima é apresentado decodificado logo abaixo. No cabeçalho está incluso o atributo ‘kid’ (id da chave) com o valor xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw, que pode ser localizado no JSON Web KeySet para este cliente aqui

{
  "alg": "PS256",
  "typ": "oauth-authz-req+jwt",
  "kid": "PWAi5ruQcHfzPzq2JFdpY7nAUh6LzTTQtDBUpOM37JQ"
}
{
  "scope": "openid opinbrasil:grant:GDERZGRWo-eOEyQ7CUfjf",
  "response_type": "code id_token",
  "redirect_uri": "https://tpp.localhost/cb",
  "code_challenge": "S2fxBULKiPP7qNvk7fyZPTqL-akIbrWqOzZZXSr5U6c",
  "code_challenge_method": "S256",
  "response_mode": "form_post",
  "state": "03518196505537e211dd08cedb12711870a56ea4888924d598c4b0640301063b",
  "nonce": "8981c8a560c21c0f8746e9b978bfc004b9274f2bcf786a3e15aa96c8dd5494dd",
  "claims": {
    "id_token": {
      "auth_time": {
        "essential": true
      },
      "national_id": {
        "essential": true
      },
      "given_name": {
        "essential": true
      },
      "acr": {
        "values": [
          "urn:opinbrasil:trustframework:gold"
        ],
        "essential": true
      }
    },
    "userinfo": {
      "auth_time": {
        "essential": true
      },
      "national_id": {
        "essential": true
      },
      "given_name": {
        "essential": true
      },
      "acr": {
        "values": [
          "urn:opinbrasil:trustframework:gold"
        ],
        "essential": true
      }
    }
  },
  "max_age": 300,
  "iss": "aCnBHjZBvD6ku3KVBaslL",
  "aud": "https://auth.localhost",
  "client_id": "aCnBHjZBvD6ku3KVBaslL",
  "jti": "q8_NScJoqu8ndrcXfj7NTCUCSd6cPI9g5I7qEyIKkSU",
  "iat": 1618664738,
  "exp": 1618665038,
  "nbf": 1618664738
}

O JWK público do JWKS retirado da uri fornecido anteriormente

{
  "kty":"RSA",
  "use":"sig",
  "x5c":["MIIG9DCCBdygAwIBAgIUHy/za0mwr7eUEasj2fXtS4sekZkwDQYJKoZIhvcNAQELBQAwdzELMAkGA1UEBhMCQlIxHjAcBgNVBAoTFU9wZW4gSW5zdXJhbmNlIEJyYXNpbDEXMBUGA1UECxMOT3BlbiBJbnN1cmFuY2UxLzAtBgNVBAMTJk9wZW4gSW5zdXJhbmNlIFNBTkRCT1ggSXNzdWluZyBDQSAtIEcxMB4XDTIyMDcxNDE3NDkwMFoXDTIzMDgxMzE3NDkwMFowgcMxCzAJBgNVBAYTAkJSMRMwEQYDVQQKEwpJQ1AtQnJhc2lsMUEwDAYDVQQLEwVUZXN0ZTAVBgNVBAsTDjE0NzIzMzc5MDAwMTcyMBoGA1UECxMTY2VydGlmaWNhZG8gZGlnaXRhbDEmMCQGA1UEAxMdT1BFTiBJTlNVUkFOQ0UgQlJBU0lMIC0gUEVFUlMxNDAyBgoJkiaJk/IsZAEBEyQ0Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWMwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC8IHx8C4J7Eyis1G25VbTvAqpa5ny0FJBZVP+K7m0F+hCLxvPhC5ZZDL4dY5pAb6EozKU/Tg70/XGNVbhZvjOvOWgNLOxYI6hiOdRfuy/8GEUQxWEoFqfS9Q24E+aw7miBacUjg9RiVvfhMRPKIZ8Qjhjd1sefI2blcCfKF8exqPcDNP3EyLuS3Ny2Hyq/ZGKXt4rpitahbpBBFnwUpDC4qfBXZ4w55OW4T1sI1+QJA8y5A4QUe2iewSmd8rOXtymiEZLTJ910R/0gRaf9Qv6pb2jzTfABRJbPUlkn5MD/h8bRljZobu/AS2v/XD+rfSdYq6/ZjCvMz20JuXdZEvqLAgMBAAGjggMpMIIDJTAMBgNVHRMBAf8EAjAAMB0GA1UdDgQWBBTY8mtqsrwa73AgQ/jxr6tXhKj3aDAfBgNVHSMEGDAWgBQe6nJx8bsl1+pttR0hY3JNExWkfjBFBggrBgEFBQcBAQQ5MDcwNQYIKwYBBQUHMAGGKWh0dHA6Ly9vY3NwLnNhbmRib3gucGtpLm9waW5icmFzaWwuY29tLmJyMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA6Ly9jcmwuc2FuZGJveC5wa2kub3BpbmJyYXNpbC5jb20uYnIvaXNzdWVyLmNybDCBkgYDVR0RBIGKMIGHoEAGBWBMAQMCoDcMNTxOYW1lIG9mIHRoZSBwZXJzb24gcmVzcG9uc2libGUgZm9yIHRoZSBvcmdhbml6YXRpb24+oBkGBWBMAQMDoBAMDjE0NzIzMzc5MDAwMTcyoBYGBWBMAQMEoA0MCzExMTExMTExMTMyoBAGBWBMAQMHoAcMBTEyMzQ1MA4GA1UdDwEB/wQEAwIGwDCCAaEGA1UdIASCAZgwggGUMIIBkAYKKwYBBAGDui9kATCCAYAwggE2BggrBgEFBQcCAjCCASgMggEkVGhpcyBDZXJ0aWZpY2F0ZSBpcyBzb2xlbHkgZm9yIHVzZSB3aXRoIFJhaWRpYW0gU2VydmljZXMgTGltaXRlZCBhbmQgb3RoZXIgcGFydGljaXBhdGluZyBvcmdhbmlzYXRpb25zIHVzaW5nIFJhaWRpYW0gU2VydmljZXMgTGltaXRlZHMgVHJ1c3QgRnJhbWV3b3JrIFNlcnZpY2VzLiBJdHMgcmVjZWlwdCwgcG9zc2Vzc2lvbiBvciB1c2UgY29uc3RpdHV0ZXMgYWNjZXB0YW5jZSBvZiB0aGUgUmFpZGlhbSBTZXJ2aWNlcyBMdGQgQ2VydGljaWNhdGUgUG9saWN5IGFuZCByZWxhdGVkIGRvY3VtZW50cyB0aGVyZWluLjBEBggrBgEFBQcCARY4aHR0cDovL3JlcG9zaXRvcnkuc2FuZGJveC5wa2kub3BpbmJyYXNpbC5jb20uYnIvcG9saWNpZXMwDQYJKoZIhvcNAQELBQADggEBAG/o37oQuU9QyFdQxiP2tRVlfgQn7Khj1xamIcuxfzhug9ztgu6dwxELkjhxsjcTxn2ynUcK3+rqg9FHZVV7pise/lGuW9HvWzzOd9nGEtKv0UmEdHidpHQ8lAnpsn2cAA+Fs1LiZqGmvvfVouIrqEM2kjnpTSpn05yj0VK83CnUsPm4aUnd1BeacqXI2GU9U6yULI0Y6ooNVkAcRq/yqjyKlo6ik70I3eK39OH4dkkgE1ooF8Qzxl1q0kVUHqjKlJiXu3VsIgihr5Sr9tDtneXEwTrMdA6vuqIQEUQWkohZCqD0m4E/j+NMwvt6lQtiJQwy8RrN6RHFiqeuTg8Mk7Q="],
  "n":"vCB8fAuCexMorNRtuVW07wKqWuZ8tBSQWVT_iu5tBfoQi8bz4QuWWQy-HWOaQG-hKMylP04O9P1xjVW4Wb4zrzloDSzsWCOoYjnUX7sv_BhFEMVhKBan0vUNuBPmsO5ogWnFI4PUYlb34TETyiGfEI4Y3dbHnyNm5XAnyhfHsaj3AzT9xMi7ktzcth8qv2Ril7eK6YrWoW6QQRZ8FKQwuKnwV2eMOeTluE9bCNfkCQPMuQOEFHtonsEpnfKzl7cpohGS0yfddEf9IEWn_UL-qW9o803wAUSWz1JZJ-TA_4fG0ZY2aG7vwEtr_1w_q30nWKuv2YwrzM9tCbl3WRL6iw",
  "e":"AQAB",
  "kid":"xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw",
  "x5u":"https://keystore.sandbox.directory.opinbrasil.com.br/4b75db2e-a0c0-4359-a077-684e88fa695c/xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw.pem",
  "x5t#256":"xSkimtEka2S1kt0EAEx2Rf6FKzwGJ-sS4Qxv37lbSiw"
}

A chave privada que foi usada para criar o JWS

Se quiser conhecer um pouco mais e exercitar, visite o site JWT-IO e conheça um pouco mais.

2.0 Interagindo com as APIs de Serviços de Confiança

Quando um aplicativo é registrado no Diretório, o serviço central usa os metadados e certificados fornecidos para criar para o software um cliente OAuth 2.0 que tem um grant type do tipo client credentials, conforme definido em RFC6749 e com um mecanismo de autenticação de cliente definido como tls_client_auth, conforme definido em RFC 8705.

Usando o ClientID listado na declaração do software (software statement) no Diretório, OpenID Connect Discovery e a configuração do OpenID Provider Issuer abaixo, um participante tem todos das informações necessárias para descobrir, autenticar e interagir com as APIs do Diretório

2.1 Emissores do Framework de Confiança do Diretório

Produção: https://auth.directory.opinbrasil.com.br/

Sandbox: https://auth.sandbox.directory.opinbrasil.com.br/

Os certificados para acesso às APIs publicadas pelas instituições participantes devem ser obrigatoriamente certificados emitidos no âmbito da ICP-Brasil.

2.2 Como se Comunicar com o Authorization Server do Diretório

Use o OpenID Issuer e a Cláusula 4 da especificação OpenID Connect Discovery para obter o documento openid-configuration.

curl https://auth.directory.opinbrasil.com.br/.well-known/openid-configuration

{
  "authorization_endpoint": "https://auth.directory.opinbrasil.com.br/auth",
  "device_authorization_endpoint": "https://auth.directory.opinbrasil.com.br/device/auth",
  "claims_parameter_supported": true,
  "claims_supported": [
    "sub",
    "email",
    "email_verified",
    "phone_number",
    "phone_number_verified",
    "address",
    "birthdate",
    "family_name",
    "gender",
    "given_name",
    "locale",
    "middle_name",
    "name",
    "nickname",
    "picture",
    "preferred_username",
    "profile",
    "updated_at",
    "website",
    "zoneinfo",
    "sid",
    "auth_time",
    "iss"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "end_session_endpoint": "https://auth.directory.opinbrasil.com.br/session/end",
  "check_session_iframe": "https://auth.directory.opinbrasil.com.br/session/check",
  "grant_types_supported": [
    "implicit",
    "authorization_code",
    "refresh_token",
    "client_credentials"
  ],
  "id_token_signing_alg_values_supported": [
    "PS256"
  ],
  "issuer": "https://auth.directory.opinbrasil.com.br",
  "jwks_uri": "https://auth.directory.opinbrasil.com.br/jwks",
  "registration_endpoint": "https://auth.directory.opinbrasil.com.br/reg",
  "response_modes_supported": [
    "form_post",
    "fragment",
    "query",
    "jwt",
    "query.jwt",
    "fragment.jwt",
    "form_post.jwt"
  ],
  "response_types_supported": [
    "code id_token",
    "code",
    "id_token",
    "none"
  ],
  "scopes_supported": [
    "openid",
    "offline_access",
    "profile",
    "email",
    "address",
    "phone",
    "directory:software"
  ],
  "subject_types_supported": [
    "public",
    "pairwise"
  ],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "PS256"
  ],
  "token_endpoint": "https://auth.directory.opinbrasil.com.br/token",
  "pushed_authorization_request_endpoint": "https://auth.directory.opinbrasil.com.br/request",
  "request_object_signing_alg_values_supported": [
    "PS256"
  ],
  "request_parameter_supported": true,
  "request_uri_parameter_supported": true,
  "require_request_uri_registration": true,
  "userinfo_endpoint": "https://auth.directory.opinbrasil.com.br/me",
  "userinfo_signing_alg_values_supported": [
    "PS256"
  ],
  "authorization_signing_alg_values_supported": [
    "PS256"
  ],
  "introspection_endpoint": "https://auth.directory.opinbrasil.com.br/token/introspection",
  "introspection_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth"
  ],
  "introspection_endpoint_auth_signing_alg_values_supported": [
    "PS256"
  ],
  "revocation_endpoint": "https://auth.directory.opinbrasil.com.br/token/revocation",
  "revocation_endpoint_auth_methods_supported": [
    "private_key_jwt",
    "tls_client_auth"
  ],
  "revocation_endpoint_auth_signing_alg_values_supported": [
    "PS256"
  ],
  "frontchannel_logout_supported": true,
  "frontchannel_logout_session_supported": true,
  "tls_client_certificate_bound_access_tokens": true,
  "claim_types_supported": [
    "normal"
  ],
  "mtls_endpoint_aliases": {
    "token_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token",
    "revocation_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token/revocation",
    "introspection_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token/introspection",
    "device_authorization_endpoint": "https://matls-auth.directory.opinbrasil.com.br/device/auth",
    "pushed_authorization_request_endpoint": "https://matls-auth.directory.opinbrasil.com.br/request",
    "userinfo_endpoint": "https://matls-auth.directory.opinbrasil.com.br/me"
  }
}

Obtenha o alias do endpoint do Mutual TLS Token, conforme definido por RFC8705 - OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens

 "mtls_endpoint_aliases": {
    "token_endpoint": "https://matls-auth.directory.opinbrasil.com.br/token",
  }

Estabeleça uma conexão TLS mútua usando o certificado de transporte registrado anteriormente e solicite um token de acesso com o escopo directory:software

curl --cert transport.pem --key transport.key https://matls-auth.directory.opinbrasil.com.br/token -X POST -d 'client_id=cd080791-9f2b-4b0d-b6a4-953be52b5971&grant_type=client_credentials&scope=directory:software'

{"access_token":"O9lA1EsQM7sAEOgmNdjcIwXAjeBqqFCDnYALhg7bysJ","expires_in":600,"token_type":"Bearer","scope":"directory:software"}

2.3 Como se Comunicar com as APIs do Diretório

As APIs do Diretório são recursos RESTful protegidos usando o Perfil de Segurança do Open Insurance Brasil. Isso significa que eles têm a mesma postura de segurança das APIs publicadas pelas seguradoras. Todas as APIs de Diretório requerem o escopo do recurso OAuth 2.0 de directory:software e são protegidos usando Mutual TLS (mTLS).

Consulte a especificação do Diretório OpenAPI v3 para o conjunto completo de endpoints disponíveis.

2.4 Descobrindo Authorization Servers de Seguradoras

Faça uma busca pelo recurso de participantes (informações públicas) e obtenha uma lista de todos os participantes e seus Authorization Servers.

curl https://data.directory.opinbrasil.com.br/participants

{
  "content": [
    {
      "OrganisationId": "c20ae180-e660-43c3-90e6-2914ace51974",
      "Status": "Active",
      "OrganisationName": "OPEN INSURANCE BRASIL",
      "CreatedOn": "2022-01-26T21:05:03.381Z",
      "LegalEntityName": "Open insurance Brasil",
      "CountryOfRegistration": "BR",
      "CompanyRegister": "VAT Number",
      "Tags": [
          "Technical Service Provider"
      ],
      "Size": "50",
      "RegistrationNumber": "123456",
      "RegistrationId": "12345678910",
      "RegisteredName": "Open insurance Brasil",
      "AddressLine1": "199 Bishopsgate",
      "AddressLine2": "string",
      "City": "London",
      "Postcode": "BA",
      "Country": "BR",
      "RequiresParticipantTermsAndConditionsSigning": true
    }

  -- resultados filtrados para brevidade

  ]
}

Filtre os participantes por aqueles que possuem Authorization Servers protegendo os recursos que você está interessado em acessar para o seu produto. No exemplo acima, existem dois Authorization Servers para ‘_’, um para o negócio de varejo e um para o corporativo.

O aplicativo agora descobriu a lista de seguradoras que estão oferecendo APIs que podem ser úteis para os usuários do aplicativo e pode gerar uma lista de ‘customer friendly names’ de seguradoras e logotipos para exibir aos clientes para permitir que eles selecionem a seguradora a partir do qual desejam compartilhar dados.

3.0 Registrando o Aplicativo com um Provedor

DCR

A partir do exemplo dado acima, podemos ver que a localização do "OpenIDDiscoveryDocument" é anunciada por cada um dos Authorization Server.

3.1 Criação de uma Declaração de Software (SSA)

Uma afirmação de declaração de software (software statement assertion - SSA) é um JWT assinado pelo Diretório que contém todas as informações sobre um aplicativo que existe em um determinado momento no Diretório. Inclui a localização de todas as chaves públicas vinculadas à esta declaração de software e todos os outros metadados de que uma seguradora precisa para validar a legitimidade do aplicativo.

Um SSA não tem período de validade, é simplesmente um registro pontual do que existia como atributos válidos no momento em que foi criado. As seguradoras devem aceitar um SSA com menos de alguns minutos, mas a janela exata pode ser diferente entre os provedores.

Obtenha um token de acesso e, em seguida, carregue a declaração do software para um aplicativo no Diretório.

curl --cert transport.pem --key transport.key https://matls-auth.directory.opinbrasil.com.br/token -X POST -d 'client_id=cd080791-9f2b-4b0d-b6a4-953be52b5971&grant_type=client_credentials&scope=directory:software'

{"access_token":"O9lA1EsQM7sAEOgmNdjcIwXAjeBqqFCDnYALhg7bysJ","expires_in":600,"token_type":"Bearer","scope":"directory:software"}

curl --cert transport.pem --key transport.key https://matls-api.directory.opinbrasil.com.br/organisations/4b75db2e-a0c0-4359-a077-684e88fa695c/softwarestatements/cd080791-9f2b-4b0d-b6a4-953be52b5971/assertion -H 'Authorization: Bearer O9lA1EsQM7sAEOgmNdjcIwXAjeBqqFCDnYALhg7bysJ'

eyJraWQiOiJzaWduZXIiLCJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiJ9.eyJzb2Z0d2FyZV9qd2tzX2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfbW9kZSI6IkxpdmUiLCJzb2Z0d2FyZV9yZWRpcmVjdF91cmlzIjpbImh0dHBzOlwvXC93d3cubmFvdmFsaWRvLmNvbS5iciJdLCJzb2Z0d2FyZV9zdGF0ZW1lbnRfcm9sZXMiOltdLCJvcmdfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL3RyYW5zcG9ydC5qd2tzIiwic29mdHdhcmVfY2xpZW50X25hbWUiOiJUZXN0ZSBTYW5kYm94Iiwib3JnX3N0YXR1cyI6IkFjdGl2ZSIsImlzcyI6Ik9wZW4gSW5zdXJhbmNlIEJyYXNpbCBTYW5kYm94IFNTQSBpc3N1ZXIiLCJvcmdfandrc190cmFuc3BvcnRfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX2p3a3NfdHJhbnNwb3J0X2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX3BvbGljeV91cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJzb2Z0d2FyZV9pZCI6ImNkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MSIsInNvZnR3YXJlX3N0YXR1cyI6IkFjdGl2ZSIsInNvZnR3YXJlX2Vudmlyb25tZW50IjoiU2FuZGJveCIsInNvZnR3YXJlX3ZlcnNpb24iOiIxLjAwIiwib3JnX25hbWUiOiJPUEVOIElOU1VSQU5DRSBCUkFTSUwgLSBQRUVSUyIsImlhdCI6MTY1NzgyOTExNCwic29mdHdhcmVfc2VjdG9yX2lkZW50aWZpZXJfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvcmVkaXJlY3RfdXJpcy5qc29uIiwic29mdHdhcmVfY2xpZW50X2lkIjoiY2QwODA3OTEtOWYyYi00YjBkLWI2YTQtOTUzYmU1MmI1OTcxIiwib3JnX2p3a3NfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvdHJhbnNwb3J0Lmp3a3MiLCJzb2Z0d2FyZV9jbGllbnRfdXJpIjoiaHR0cHM6XC9cL3d3dy5uYW92YWxpZG8uY29tLmJyIiwic29mdHdhcmVfbG9nb191cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJvcmdfaWQiOiI0Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWMiLCJvcmdfandrc191cmkiOiJodHRwczpcL1wva2V5c3RvcmUuc2FuZGJveC5kaXJlY3Rvcnkub3BpbmJyYXNpbC5jb20uYnJcLzRiNzVkYjJlLWEwYzAtNDM1OS1hMDc3LTY4NGU4OGZhNjk1Y1wvYXBwbGljYXRpb24uandrcyIsIm9yZ19udW1iZXIiOiIxNDcyMzM3OTAwMDE3MiIsInNvZnR3YXJlX2p3a3NfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvYXBwbGljYXRpb24uandrcyIsInNvZnR3YXJlX3JvbGVzIjpbXSwib3JnYW5pc2F0aW9uX2NvbXBldGVudF9hdXRob3JpdHlfY2xhaW1zIjpbXX0.bdWayyhABvNGnT7Vmsdd5ZTht1oYBm_hHRAAyRGD-lCmNi08HDFH-8RzjFsMJ5ZWzS99mwwVrCBph0YcbwfzWuSu9uFdd-bwvfhXFhkNDzQHuRMOF1QTHd0C8r3N-_CkBtYWyXXNFGiREyXjFn8Muvw3fGSr98sy01PDlNyZlxxpBTU9-nz2r-WxwwVyTJyVfz8wVXrrX3_H19Ty3vwiqAbf0tSPyfXFEe3XQE6XJ8W93Ec9M2CzB3PuaaNvgsa2f4T6tT3yHqUfnRQuqf1FCc3raxxn7tVAB-G1yJ9bz-ZaKdsjX2nWCGhJR41rIPlAGv85EsESAo_JSHpfZW0EbA

3.2 Enviando uma Solicitação de Dynamic Client Registration (RFC7591)

Consulte o Dynamic Client Registration do Open Insurance Brasil

3.3 Salvando o Token de Dynamic Registration Management (RFC7592)

Consulte o Dynamic Client Registration do Open Insurance Brasil

3.4 Modificando um cliente usando Dynamic Client Management Token (RFC7592)

Consulte o Dynamic Client Registration do Open Insurance Brasil

4.0 Obtendo Acesso aos Recursos dos Clientes

Consent

Para todas as opções, incluindo todos os códigos de permissão, consulte o Consent API. Os exemplos a seguir são exemplos mínimos, mas funcionais para demonstrar o fluxo de ponta a ponta. Esses exemplos pressupõem que o cliente está se comunicando com um provedor de OpenID, aproveitando o mecanismo de autenticação de endpoint do token tls_client_auth. Exemplos alternativos estão disponíveis no apêndice.

4.1 Pré-requisitos

Esses exemplos não normativos presumem que o cliente OAuth descobriu os locais de todos os 'endpoints' necessários para se comunicar com os recursos das seguradoras do Diretório, incluindo o recurso de consentimento, os recursos de dados e o documento de descoberta de autorização OpenID do Diretório.

4.2 Criando Consentimento

Obtendo um Token de Acesso com escopo 'consents'

curl --cert transport.pem --key transport.key https://matls-auth.amazinginsurance.com.br/token -X POST -d 'client_id=clientIdFromAmazingInsurance&grant_type=client_credentials&scope=consents'

{"access_token":"2Pjwts8m1KRZmm0aJyXbOTB8zRosN55fo8Ewdulhxxa","expires_in":600,"token_type":"Bearer","scope":"consents"}

Criando um recurso de consentimento

curl --cert transport.pem --key transport.key -H 'Authorization: Bearer 2Pjwts8m1KRZmm0aJyXbOTB8zRosN55fo8Ewdulhxxa'
-H "Content-Type: application/json"
 https://matls-api.amazinginsurance.com.br/consents/v1/consents
--data
'{
  "data": {
    "loggedUser": {
      "document": {
        "identification": "11111111111",
        "rel": "CPF"
      }
    },
    "businessEntity": {
      "document": {
        "identification": "11111111111111",
        "rel": "CNPJ"
      }
    },
    "permissions": [
      CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ,
      CUSTOMERS_PERSONAL_QUALIFICATION_READ,
      CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
    ],
    "expirationDateTime": "2022-02-01T23:59:59Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2022-02-01T23:59:59Z"
  }
}'

Resposta

{
  "data": {
    "consentId": "urn:seguradoraex:C1DD33123",
    "creationDateTime": "2021-05-21T08:30:00Z",
    "status": "AWAITING_AUTHORISATION",
    "statusUpdateDateTime": "2021-05-21T08:30:00Z",
    "permissions": [
      CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ,
      CUSTOMERS_PERSONAL_QUALIFICATION_READ,
      CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
    ],
    "expirationDateTime": "2022-02-01T23:59:59Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2022-02-01T23:59:59Z"
  },
  "links": {
    "self": "https://matls-api.amazinginsurance.com.br/consents/urn:seguradoraex:C1DD33123"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

4.3 Autorizando Consentimento - Redirecionar

4.3.1 Criar OpenID Connect Request Object

Diferentes métodos de autenticação (private_key_jwt e tls_client_auth) e de encaminhamento do Request Object (com e sem uso de PAR) podem ser suportados pelos Authorization Servers de acordo com a especificação FAPI-1.0 Part 2 - Advanced.

Portanto, como reforça o perfil de segurança para o Open Finance Brasil (item 8 da seção 5.2.3 dos requisitos de segurança para o cliente confidencial), todas as 4 combinações de métodos devem ser suportados pelos clientes de API.

A tabela abaixo reflete os diferentes profiles de segurança e combinações que devem ser suportados por todos os clientes de API (conforme os profiles certificados pela OIDF para o Open Insurance Brasil).

Perfil da certificação OIDF
BR-OB Adv. OP w/ MTLS
BR-OB Adv. OP w/ Private Key
BR-OB Adv. OP w/ MTLS, PAR
BR-OB Adv. OP w/ Private Key, PAR

Todos os requisitos para o OpenID Request Object estão incluídos no Perfil de Segurança do Open Insurance Brasil. Veja o exemplo com JWS a seguir:

{
 "alg": "PS256",
 "typ": "oauth-authz-req+jwt",
 "kid": "PWAi5ruQcHfzPzq2JFdpY7nAUh6LzTTQtDBUpOM37JQ"
}
.
{
  "scope": "openid consent:urn:amazinginsurance:0be7a3bb-33e6-4d73-b60a-9523aee6cc0d insurance-auto",
  "response_type": "code id_token",
  "redirect_uri": "https://tpp.localhost/cb",
  "code_challenge": "0q5idWeuyFAGeHHpawD3k4mjE7WzPhw6hOdKbnAQY7s",
  "code_challenge_method": "S256",
  "state": "19a1456013b8be71e6ce89916c9723e0642e1eb42a9360146cc84178f2bc928e",
  "nonce": "8dedaf2c53f7ba7294825ca25e45aa544c3feda8fd4ac16220c216e973ad5fd7",
  "claims": {
    "id_token": {
      "auth_time": {
        "essential": true
      },
      "cpf": {
        "essential": true
      },
      "given_name": {
        "essential": true
      },
      "acr": {
        "values": [
          "brasil:openinsurance:standard"
        ],
        "essential": true
      }
    }
  },
  "max_age": 300,
  "iss": "clientIdFromAmazingInsurance",
  "aud": "https://auth.amazinginsurance.com.br",
  "client_id": "clientIdFromAmazingInsurance",
  "jti": "_fj7iamgC1wDzh8KXaJ7XzJiEK_s25DhoDs7uAxpU-k",
  "iat": 1618672338,
  "exp": 1618672638,
  "nbf": 1618672338
}
Assinatura omitida por questões de brevidade

4.3.1.1 Solicitação de Claims Específicas

Também é opcional para receptoras solicitar claims de identidade ('Identity Claims') adicionais, incluindo CPF e CNPJ. Essas claims são definidas no Perfil de Segurança do Open Insurance Brasil. Também é possível para um receptor solicitar que uma claim corresponda a um determinado valor, baseando-se em OpenID Connect Core Clause 5.5.1 para solicitar claims individuais.

Por exemplo:

"cpf": {
        "essential": true,
        value: 12345678123
      },

Nesse exemplo seria exigido que o provedor OpenID retornasse apenas uma autenticação e autorização bem-sucedidas se o usuário que estava autenticando poderia ser confirmado pela seguradoras que eles tinham um número de CPF de 12345678123. Se a seguradora não puder confirmar este número, então a autenticação deve falhar.

Solicitar reivindicações de valor específico é totalmente opcional para o receptor.

4.3.2 Redirecionar o Usuário ao Authorization Server para Autorização

De acordo com o OpenID Connect Core.

https://auth.amazinginsurance.com.br/auth?client_id=clientIdFromAmazingInsurance&scope=openid&request=eyJhbGciOiJQUzI1NiIsInR5cCI6Im9hdXRoLWF1dGh6LXJlcStqd3QiLCJraWQiOiJQV0FpNXJ1UWNIZnpQenEySkZkcFk3bkFVaDZMelRUUXRE...j1CpNMT7NtDerEl32E8plGnsuA

4.3.3 Obtenção de Token de Acesso por Meio de Troca de Código de Autorização

Conforme RFC 7636 Proof Key for Code Exchange

4.3.4 Verificação do Status do Recurso de Consentimento

Neste ponto, um receptor pode, opcionalmente, verificar o status da solicitação de consentimento para ver se mudou para totalmente autorizado. Esta etapa não deverá ser necessária para recursos que não requerem consentimento de múltiplos indivíduos, entretanto, para contas comerciais ou contas conjuntas com requisitos de acesso especiais, a seguradora pode demorar um pouco para obter as autorizações adicionais necessárias para que esse consentimento seja totalmente autorizado. Os receptores não devem abusar da verificação do status da API de consentimento.

curl --cert transport.pem --key transport.key -H 'Authorization: Bearer 2Pjwts8m1KRZmm0aJyXbOTB8zRosN55fo8Ewdulhxxa'
 https://matls-api.amazinginsurance.com.br/consents/v1/consents/urn:amazinginsurance:0be7a3bb-33e6-4d73-b60a-9523aee6cc0d

{
  "data": {
    "consentId": "urn:seguradoraex:C1DD33123",
    "creationDateTime": "2021-05-21T08:30:00Z",
    "status": "AWAITING_AUTHORISATION",
    "statusUpdateDateTime": "2021-05-21T08:30:00Z",
    "permissions": [
      CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ,
      CUSTOMERS_PERSONAL_QUALIFICATION_READ,
      CUSTOMERS_PERSONAL_ADITTIONALINFO_READ..
    ],
    "expirationDateTime": "2022-02-01T23:59:59Z",
    "transactionFromDateTime": "2021-01-01T00:00:00Z",
    "transactionToDateTime": "2022-02-01T23:59:59Z"
  },
  "links": {
    "self": "https://matls-api.amazinginsurance.com.br/consents/urn:seguradoraex:C1DD33123"
  },
  "meta": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

4.3.5 Acesso aos Recursos

Com o token de acesso que foi retornado em 4.3.3, o receptor agora tem a capacidade de chamar os recursos dos clientes.

Dynamic Client Registration (DCR)

Prefácio

A Estrutura Inicial do Open Insurance Brasil é responsável por criar os padrões e especificações necessários para atender aos requisitos e obrigações da Legislação do Open Insurance do Brasil, conforme originalmente delineado pela SUSEP. É possível que alguns dos elementos deste documento estejam sujeitos a direitos de patente. A Estrutura Inicial não se responsabiliza pela identificação de qualquer ou todos os direitos de patente.

O Perfil de Segurança Financial-grade API 1.0 do Open Insurance Brasil consiste nas seguintes partes:

Open Finance Brasil Financial-grade API Security Profile 1.0
Open Insurance Brasil Dynamic Client Registration Profile 1.0

Essas partes devem ser usadas com RFC6749, RFC6750, RFC7636, OIDC, OIDR, RFC7591, RFC7592, FAPI-1-Baseline e FAPI-1-Advanced

Introdução

O Perfil de Registro de Cliente Dinâmico (DCR - Dynamic Client Registration) do Financial-grade API (FAPI) do Open Insurance Brasil é um perfil de RFC7591, RFC7592 e OIDR que visa fornecer diretrizes de implementação específicas para segurança e interoperabilidade que podem ser aplicadas à identificação, registro e gerenciamento de Clients OAuth operando no ecossistema Open Insurance Brasil.

Embora seja possível codificar um OpenID Provider e Relying Party desde o princípio usando esta especificação, o principal público para esta especificação são as partes que já possuem uma implementação certificada do OpenID Connect e desejam obter a certificação para o Open Insurance Brasil.

Convenções Notacionais

As palavras-chave "deve" (shall), "não deve" (shall not), "deveria" (should), "não deveria" (should not) e "pode" (may) presentes nesse documento devem ser interpretadas conforme as diretrizes descritas em ISO Directive Part 2 observando seguinte equivalência:

"deve" => equivalente ao termo "shall" e expressa um requerimento definido no documento (nas traduções é similar ao termo "must", que pode denotar um requerimento externo ao documento);
"não deve" => equivalente ao termo "shall not" e também expressa um requerimento definido no documento;
"deveria" e "não deveria"=> equivalente ao termo "should" e "should not" e expressa uma recomendação
"pode" => equivalente ao termo "may" indica uma permissão

Estas palavras-chave não são usadas como termos de dicionário, de modo que qualquer ocorrência deles deve ser interpretada como palavras-chave e não devem ser interpretados com seus significados de linguagem natural.

1. Escopo

Este documento especifica o método de

aplicativos cadastrados no Diretorio de Participantes do Open Insurance para descobrir OpenID Providers que oferecem serviços no ecossistema Open Insurance Brasil;
aplicativos para usar o OpenID Connect Registration para integrar seus aplicativos com OpenID Providers das seguradoras; e
aplicativos para usar OAuth 2.0 Dynamic Client Registration Management Protocol para gerenciar seus aplicativos com OpenID Providers;

Este documento é aplicável a todos os participantes do Open Insurance no Brasil.

2. Referências normativas

Os seguintes documentos referenciados são indispensáveis para a aplicação deste documento. Para referências datadas, apenas a edição citada se aplica. Para referências não datadas, a última edição do documento referenciado (incluindo quaisquer emendas) se aplica.

ISODIR2 - ISO/IEC Directives Part 2
RFC6749 - The OAuth 2.0 Authorization Framework
RFC6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage
RFC7636 - Proof Key for Code Exchange by OAuth Public Clients
RFC6819 - OAuth 2.0 Threat Model and Security Considerations
RFC7519 - JSON Web Token (JWT)
RFC7591 - OAuth 2.0 Dynamic Client Registration Protocol
RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol
BCP195 - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)
OIDC - OpenID Connect Core 1.0 incorporating errata set 1
FAPI-CIBA - Financial-grade API: Client Initiated Backchannel Authentication Profile
RFC4514 - Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names
RFC4517 - Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules
OIDD - OpenID Connect Discovery 1.0 incorporating errata set 1
OIDR - OpenID Connect Registration 1.0 incorporating errata set 1
RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens
JARM - Financial-grade API: JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)
PAR - OAuth 2.0 Pushed Authorization Requests
JAR - OAuth 2.0 JWT Secured Authorization Request
FAPI-1-Baseline - Financial-grade API Security Profile 1.0 - Part 1: Baseline
FAPI-1-Advanced - Financial-grade API Security Profile 1.0 - Part 2: Advanced
OFB-FAPI - Open Finance Brasil Financial-grade API Security Profile 1.0
OFB-Cert-Standards - Open Insurance Brasil x.509 Certificate Standards
OFB-DCR/DCM-Swagger - DCR & DCM Swagger

3. Termos e definições

Para efeitos deste documento, aplicam-se os termos definidos em RFC6749, RFC6750, RFC7636, OpenID Connect Core e ISO29100.

4. Símbolos e Termos abreviados

API – Application Programming Interface (Interface de Programação da Aplicação)
DCR – Dynamic Client Registration (Registro de Cliente Dinâmico)
FAPI - Financial-grade API
HTTP – Hyper Text Transfer Protocol
OIDF - OpenID Foundation
REST – Representational State Transfer
SS – Software Statement (Declaração de Software)
SSA – Software Statement Assertion (Afirmação de Declaração de Software)
TLS – Transport Layer Security

5. Introdução

O ecossistema Open Insurance Brasil apoia-se em um provedor de confiança ou diretório de participantes como a fonte mais valiosa de informações sobre participantes credenciados e softwares que estão autorizados a participar do ecossistema Open Insurance Brasil.

Os serviços do Diretório incluem:

Registro e gerenciamento de software
Registro e gerenciamento de credenciais de software usando certificados ICP
Geração de Software Statement Assertion (SSA)

Os participantes do ecossistema devem aproveitar esses serviços para facilitar o registro de cliente OAuth orientado por API usando o processo descrito na cláusula 3.1.1 do RFC7591 com metadados adicionais necessários para oferecer suporte ao OpenID Connect definido em OpenID Connect Registration.

É importante reforçar que o payload de registro de clientes possui a maior parte de seus atributos não obrigatórios, e que os atributos cujos valores conflitem com os presentes no software statement assertion serão sobrepostos pelos valores do próprio software statement assertion emitido pelo diretório central. Nem todos os metadados que um cliente deseja fornecer podem estar contidos em um software statement, por exemplo, alternativa Metadata Languages and Script values. Há casos ainda de metadados de cliente que são um subconjunto dos valores existentes no SSA, como por exemplo os redirect_URIs.

6. Provisionamentos do OpenID Connect Discovery do Open Insurance Brasil

6.1 Servidor de Autorização

O servidor de autorização deve suportar OpenID Connect Discovery conforme exigido pelo Financial-grade API Security Profile 1.0 - Part 1: Baseline. Este suporte deve estar explicito tanto na forma como o Servidor de Autorização está registrado no Diretório de Participantes quanto na declaração dos seus atributos no arquivo de Discovery (well-known), respeitando os mecanismos de autenticação certificados pela institição através dos testes de conformidade do Open Insurance Brasil.

Adicionalmente, o Servidor de Autorização:

deve anunciar sua presença no ecossistema Open Insurance Brasil, sendo listada no Diretório de Participantes;
deve anunciar todos os recursos API REST do Open Insurance Brasil protegidos pelo Provedor OpenID no Diretório de Participantes;
deve anunciar suporte para todos os mecanismos de assinatura, criptografia, autenticação e padrões necessários para suportar o Open Finance Brasil Financial API;
deve anunciar suporte para OpenID Dynamic Client Registration;
deve anunciar mtls_endpoint_aliases de acordo com a cláusula 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication e Certificate-Bound Access Tokens o token_endpoint, registration_endpoint e userinfo_endpoint;
se suportar OAuth 2.0 Pushed Authorisation Requests, deve anunciar por meio de OIDD mtls_endpoint_aliases o push_authorization_request_endpoint;
se suportar Financial API - Client Initiated Back Channel Authentication, deve anunciar através de OIDD mtls_endpoint_aliases o backchannel_authentication_endpoint;

6.2 Cliente

O cliente deve suportar OpenID Connect Discovery conforme exigido pelo Financial-grade API Security Profile 1.0 - Part 1: Baseline.

Além disso, o Cliente

deve contar com serviços de descoberta do ecossistemas fornecidos apenas pelo Diretório de Participantes;
deve derivar os metadados necessários do Authorization Server somente por meio do serviço OpenID Connect Discovery dos Authorization Servers;
quando presente, deve usar endpoints anunciados em mtls_endpoint_aliases conforme a cláusula 5 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication e Certificate-Bound Access Tokens;

7. Provisionamento de registro OpenID Connect do Open Insurance Brasil

7.1 Servidor de Autorização

O servidor de autorização deve suportar as RFCs de Dynamic Client Registration (DCR) RFC7591, Dynamic Client Management (DCM) RFC7592 e OpenID Registration

Além disso, o servidor de autorização

deve rejeitar as solicitações de registro de cliente dinâmico não realizadas em uma conexão protegida com mTLS usando certificados emitidos pelo Brasil ICP (produção) ou o Diretório de Participantes (sandbox);
deve validar que a solicitação contém software_statement JWT assinado usando o algoritmo PS256 emitido pelo Diretório de Participantes do Open Insurance Brasil;
deve validar que o software_statement foi emitido (iat - issued at) não mais de 5 minutos antes do pedido ser recebido;
deve validar que um atributo jwks (definida por valor) não foi incluído, e sim declarado como referência no atributo jwks_uri;
deve, quando informado, validar que o jwks_uri corresponda ao software_jwks_uri fornecido na declaração do software;
deve exigir e validar que o redirect_uris corresponda ou contenha um subconjunto dos valores de software_redirect_uris fornecidos no software_statement;
deve exigir e validar que todos os mecanismos de autenticação de cliente cumpram os requisitos definidos nas RFC7591 e RFC7592, através da validação do registration_access_token e, como conexão segura, da cadeia de certificados confiáveis ICP-Brasil.
deve validar se os escopos solicitados são adequados para as permissões regulatórias autorizadas da instituição e contidas no software_statement. A relação de permissões regulatórias e os escopos correspondentes está descrita nas seções a seguir.
deve, sempre que possível, validar os metadados declarados pelo cliente em relação aos metadados fornecidos no software_statement, adotando os valores presentes no SSA com precedência.
deve aceitar todos os nomes x.500 AttributeType definidas no Distinguished Name dos Perfis de Certificado x.509 definidos em Open Insurance Brasil x.509 Certificate Standards;
se for compatível com o mecanismo de autenticação do cliente tls_client_auth, conforme definido em RFC8705, somente deve aceitar tls_client_auth_subject_dn como uma indicação do valor do atributo subject do certificado, conforme definido na cláusula 2.1.2 RFC8705;
o valor do campo UID do certificado deve coincidir com o enviado no SSA, onde o campo UID deve conter o valor do campo software_id do SSA.
o valor do campo organizationIdentifier do certificado deve conter o prefixo correspondente ao Registration Reference OPIBR- seguido do valor do campo org_id do SSA.
deve, durante o processo de handshake TLS, usar a regra distinguishedNameMatch para comparar os valores DN conforme definido na [RFC4517].
deve garantir a integridade do estoque de consentimentos ativos, mesmo após eventuais mudanças sistêmicas, para que taís alterações sejam transparentes para as instituições receptora de dados.
deve realizar recertificação FAPI e DCR da OIDF após eventuais mudanças sistêmicas.

Estas disposições aplicam-se igualmente ao processamento de pedidos RFC7591, RFC7592 e OpenID Registration

7.1.1 Aplicando Server Defaults

Quando as propriedades de uma solicitação DCR não estão incluídas e não são obrigatórias na especificação, o Authorization Server deve aplicar os padrões do cliente da seguinte maneira:

deve selecionar e aplicar o algoritmo de criptografia e a escolha da cifra a partir dos conjuntos mais recomendados de cifra da IANA que são suportados pelo Servidor de Autorização;
deve preencher defaults a partir de valores da afirmação de software_statement, sempre que possível;
deve conceder ao cliente permissão para o conjunto completo de escopos potenciais com base nas permissões regulatórias de softwares incluídas no software_statement;

7.1.2 Análise do Distinguished Name do Certificado

A cláusula 3 do Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names define os OIDs obrigatórios cujas as strings do AttributeType (descritores) devem ser reconhecidos pelos implementadores. Esta lista obrigatória não inclui vários dos OIDs definidos em Open Insurance Brasil x.509 Certificate Standards, nem existe um mecanismo definido para os Servidores de Autorização publicarem informações sobre o formato que eles esperam de uma Solicitação Dinâmica de Registro do Cliente (Dynamic Client Registrarion) que inclui um tls_client_auth_subject_dn.

Para resolver essa ambiguidade, o Servidor de Autorização deve aceitar exclusivamente os AttributeType (descritores) definidas no último parágrafo da cláusula 3 RFC4514 em formato string, também deve aceitar em formato OID, com seus valores em ASN.1, todos os AttributeTypes definidos no Distinguished Name Open Insurance Brasil x.509 Certificate Standards ou adicionados pela Autoridade Certificadora.

Em caso de não atendimento destes requisitos o Servidor de Autorização deverá rejeitar o registro.

Segue na tabela abaixo como deve ser feita a decodificação:

Obtenha na ordem reversa os atributos do certificado
Concatene cada RDN (RelativeDistinguishedName) com uma virgula (',')
Use as strings da RFC (CN, L, ST, O, OU, C, Street, DC, UID) com o valor dos seus atributos legível para humanos
Use os OIDs dos atributos definidos nesta especificação para uso no OFB (businessCategory = OID 2.5.4.15, jurisdictionCountryName = OID 1.3.6.1.4.1.311.60.2.1.3, serialNumber = OID 2.5.4.5) com o valor dos seus atributos em formato ASN.1 seguindo a RFC4514, sendo que:
- Os nomes dos atributos devem ser definidos seguindo a notação ponto-decimal, sem adição de prefixo “OID”, ex. “2.5.4.15”, seguido dos sinais de (‘=#’) mais o valor hexadecimal do atributo, exemplo final: 2.5.4.15=#0C1450726976617465204F7267616E697A6174696F6E
- Não há qualquer restrição para as codificações/formatações utilizadas nos valores dos atributos. Deve ser respeitado o uso em hexadecimal apresentado na codificação utilizada no atributo do certificado (PrintableString, UTF8String, etc). Este item atende à opcionalidade do formato já estabelecido pela AC frente aos normativos ICP e ao itens 2.3, 2.4 e 5.2 da RFC4514.

Seguem abaixo exemplos para os atributos obrigatórios da CAs atualmente ativas:

subject_dn	Issuer
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR	issuer=CN=Open Insurance SANDBOX Issuing CA - G1,OU=Open Insurance,O=Open Insurance Brasil,C=BR
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR	issuer=CN=Autoridade Certificadora do SERPRO SSLv1,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR	issuer=CN=AC SOLUTI SSL EV,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR	issuer=CN=AC SERASA SSL EV,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR	issuer=CN=AC Certisign ICP-Brasil SSL G2,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR
UID=67c57882-043b-11ec-9a03-0242ac130003, 1.3.6.1.4.1.311.60.2.1.3=#13024252, 2.5.4.15=#131450726976617465204f7267616e697a6174696f6e, 2.5.4.5=#130e3133333533323336303030313839, CN=mycn.insurance.gov.br,2.5.4.97=OPIBR-497e1ffe-b2a2-4a4e-8ef0-70633fd11b59, O=My Public Insurance, L=BRASILIA, ST=DF, C=BR	issuer=CN=AC VALID SSL EV,OU=Autoridade Certificadora Raiz Brasileira v10,O=ICP-Brasil,C=BR

7.2 Funções regulatórias para mapeamentos OpenID e OAuth 2.0

Para participar do ecossistema do Open Insurance, as instituições credenciadas devem se cadastrar no Diretório de Participantes de acordo com seus papéis regulatórios. Essas funções refletem a autorização do SUSEP para as instituições e, consequentemente, as APIs que podem utilizar.

A tabela a seguir descreve as funções regulatórias do Open Insurance e o mapeamento de escopos do OAuth 2.0 relacionado. Se os escopos forem omitidos durante o processo de DCR, o Servidor de Autorização deve conceder o conjunto completo de escopos potenciais com base nas funções regulatórias registradas para a seguradora, conforme descrito na seção Server Defaults.

Papel Regulador	Descrição	Escopos Permitidos (em construção)	Fase-alvo
DADOS	Instituição transmissora / receptora de dados	openid consents resources customers insurance-acceptance-and-branches-abroad insurance-auto insurance-aviation insurance-financial-risk insurance-nautical insurance-nuclear insurance-patrimonial insurance-petroleum insurance-responsibility	Fase 2

É necessário validar as roles ativas no software_statement da aplicação. Na validação dessa informação deve ser utilizado o campo software_statement_roles, e deve ser verificado se as roles listadas estão ativas.

7.3 Registro do Cliente

No processo de registro do cliente, utilizando-se o método de autenticação tls_client_auth, o cliente deve encaminhar o campo tls_client_auth_subject_dn com os AttibuteTypes(Descritores) em formato definido no item 7.1.2 Análise do Distinguished Name do Certificado. Em caso de não aderencia a este padrão o registro será rejeitado.

8. Declaração de Software

Uma declaração de software (software_statement) é um JSON Web Token (JWT) que afirma valores de metadados sobre o software cliente como um todo. Na estrutura do Open Insurance Brasil, esse software_statement é assinado pelo Diretório de Participantes, e sua assinatura DEVE ser validada pelos Servidores de Autorizacao usando as chaves públicas disponíveis na seção a seguir.

8.1 Atributos da Declaração de Software (Claims)

O exemplo a seguir contém todos os atributos atualmente incluídos em um software_statement:

{
  "software_mode": "Live",
  "software_redirect_uris": [
    "https://www.raidiam.com/insurance/cb"
  ],
  "software_statement_roles": [
    {
      "role": "DADOS",
      "authorisation_domain": "Open Insurance",
      "status": "Active"
    }
  ],
  "software_client_name": "Raidiam Insurance",
  "org_status": "Active",
  "software_client_id": "Cki1EbvjwyhPB12NGLlz2",
  "iss": "Open Insurance Brasil prod SSA issuer",
  "software_tos_uri": "https://www.raidiam.com/insurance/tos.html",
  "software_client_description": "Raidiam Insurance leverage cutting edge open insurance access to bring you real time up to date views of your insurances",
  "software_jwks_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/application.jwks",
  "software_policy_uri": "https://www.raidiam.com/insurance/policy.html",
  "software_id": "25556d5a-b9dd-4e27-aa1a-cce732fe74de",
  "software_client_uri": "https://www.raidiam.com/insurance.html",
  "software_jwks_inactive_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/inactive/application.jwks",
  "software_jwks_transport_inactive_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/inactive/transport.jwks",
  "software_jwks_transport_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/transport.jwks",
  "software_logo_uri": "https://www.raidiam.com/insurance/logo.png",
  "org_id": "b961c4eb-509d-4edf-afeb-35642b38185d",
  "org_number": "112233445566",
  "software_environment": "production",
  "software_version": "1.1",
  "software_roles": [
    "DADOS"
  ],
  "org_name": "Open Insurance Brasil",
  "iat": 1620060821,
  "organisation_competent_authority_claims": [
    {
      "authorisation_domain": "Open Insurance",
      "authorisations": [],
      "registration_id": "13353236-OIB-DADOS",
      "authority_id": "687a1c94-b360-4e04-9589-0fa5cb16451b",
      "authority_name": "SUSEP",
      "authorisation_role": "DADOS",
      "authority_code": "SUSEP",
      "status": "Active"
    }
  ]
}

9. Processamento de solicitação de registro de cliente dinâmico

DCR

9.1 Enviar uma solicitação com uma declaração de software

Este exemplo inclui vários campos opcionais, alguns dos quais podem não ser aplicáveis a algumas implantações. Para um guia completo dos atributos e sua obrigatoriedade, consultar o Swagger DCR. A quebra de linha dentro dos valores são apenas para fins de exibição.

POST /reg HTTP/1.1
Host: auth.raidiam.com
Content-Type: application/json
{
"application_type": "web",
"grant_types": [
    "client_credentials",
    "authorization_code",
    "refresh_token",
    "implicit"
],
"id_token_signed_response_alg": "PS256",
"require_auth_time": false,
"response_types": [
    "code id_token",
    "id_token"
],
"software_statement": "eyJraWQiOiJzaWduZXIiLCJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiJ9.eyJzb2Z0d2FyZV9qd2tzX2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfbW9kZSI6IkxpdmUiLCJzb2Z0d2FyZV9yZWRpcmVjdF91cmlzIjpbImh0dHBzOlwvXC93d3cubmFvdmFsaWRvLmNvbS5iciJdLCJzb2Z0d2FyZV9zdGF0ZW1lbnRfcm9sZXMiOltdLCJvcmdfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL3RyYW5zcG9ydC5qd2tzIiwic29mdHdhcmVfY2xpZW50X25hbWUiOiJUZXN0ZSBTYW5kYm94Iiwib3JnX3N0YXR1cyI6IkFjdGl2ZSIsImlzcyI6Ik9wZW4gSW5zdXJhbmNlIEJyYXNpbCBTYW5kYm94IFNTQSBpc3N1ZXIiLCJvcmdfandrc190cmFuc3BvcnRfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX2p3a3NfdHJhbnNwb3J0X2luYWN0aXZlX3VyaSI6Imh0dHBzOlwvXC9rZXlzdG9yZS5zYW5kYm94LmRpcmVjdG9yeS5vcGluYnJhc2lsLmNvbS5iclwvNGI3NWRiMmUtYTBjMC00MzU5LWEwNzctNjg0ZTg4ZmE2OTVjXC9jZDA4MDc5MS05ZjJiLTRiMGQtYjZhNC05NTNiZTUyYjU5NzFcL2luYWN0aXZlXC90cmFuc3BvcnQuandrcyIsInNvZnR3YXJlX3BvbGljeV91cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJzb2Z0d2FyZV9pZCI6ImNkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MSIsInNvZnR3YXJlX3N0YXR1cyI6IkFjdGl2ZSIsInNvZnR3YXJlX2Vudmlyb25tZW50IjoiU2FuZGJveCIsInNvZnR3YXJlX3ZlcnNpb24iOiIxLjAwIiwib3JnX25hbWUiOiJPUEVOIElOU1VSQU5DRSBCUkFTSUwgLSBQRUVSUyIsImlhdCI6MTY1NzgyOTExNCwic29mdHdhcmVfc2VjdG9yX2lkZW50aWZpZXJfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvcmVkaXJlY3RfdXJpcy5qc29uIiwic29mdHdhcmVfY2xpZW50X2lkIjoiY2QwODA3OTEtOWYyYi00YjBkLWI2YTQtOTUzYmU1MmI1OTcxIiwib3JnX2p3a3NfaW5hY3RpdmVfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2luYWN0aXZlXC9hcHBsaWNhdGlvbi5qd2tzIiwic29mdHdhcmVfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvdHJhbnNwb3J0Lmp3a3MiLCJzb2Z0d2FyZV9jbGllbnRfdXJpIjoiaHR0cHM6XC9cL3d3dy5uYW92YWxpZG8uY29tLmJyIiwic29mdHdhcmVfbG9nb191cmkiOiJodHRwczpcL1wvd3d3Lm5hb3ZhbGlkby5jb20uYnIiLCJvcmdfaWQiOiI0Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWMiLCJvcmdfandrc191cmkiOiJodHRwczpcL1wva2V5c3RvcmUuc2FuZGJveC5kaXJlY3Rvcnkub3BpbmJyYXNpbC5jb20uYnJcLzRiNzVkYjJlLWEwYzAtNDM1OS1hMDc3LTY4NGU4OGZhNjk1Y1wvYXBwbGljYXRpb24uandrcyIsIm9yZ19udW1iZXIiOiIxNDcyMzM3OTAwMDE3MiIsInNvZnR3YXJlX2p3a3NfdXJpIjoiaHR0cHM6XC9cL2tleXN0b3JlLnNhbmRib3guZGlyZWN0b3J5Lm9waW5icmFzaWwuY29tLmJyXC80Yjc1ZGIyZS1hMGMwLTQzNTktYTA3Ny02ODRlODhmYTY5NWNcL2NkMDgwNzkxLTlmMmItNGIwZC1iNmE0LTk1M2JlNTJiNTk3MVwvYXBwbGljYXRpb24uandrcyIsInNvZnR3YXJlX3JvbGVzIjpbXSwib3JnYW5pc2F0aW9uX2NvbXBldGVudF9hdXRob3JpdHlfY2xhaW1zIjpbXX0.bdWayyhABvNGnT7Vmsdd5ZTht1oYBm_hHRAAyRGD-lCmNi08HDFH-8RzjFsMJ5ZWzS99mwwVrCBph0YcbwfzWuSu9uFdd-bwvfhXFhkNDzQHuRMOF1QTHd0C8r3N-_CkBtYWyXXNFGiREyXjFn8Muvw3fGSr98sy01PDlNyZlxxpBTU9-nz2r-WxwwVyTJyVfz8wVXrrX3_H19Ty3vwiqAbf0tSPyfXFEe3XQE6XJ8W93Ec9M2CzB3PuaaNvgsa2f4T6tT3yHqUfnRQuqf1FCc3raxxn7tVAB-G1yJ9bz-ZaKdsjX2nWCGhJR41rIPlAGv85EsESAo_JSHpfZW0EbA",
"subject_type": "public",
"token_endpoint_auth_method": "private_key_jwt",
"request_object_signing_alg": "PS256",
"require_signed_request_object": true,
"require_pushed_authorization_requests": false,
"tls_client_certificate_bound_access_tokens": true,
"client_id": "aCnBHjZBvD6ku3KVBaslL",
"client_name": "Raidiam Insurance",
"client_uri": "https://www.raidiam.com/insurance.html",
"request_object_encryption_alg": "RSA-OAEP",
"request_object_encryption_enc": "A256GCM"
"jwks_uri": "https://keystore.directory.opinbrasil.com.br/b961c4eb-509d-4edf-afeb-35642b38185d/25556d5a-b9dd-4e27-aa1a-cce732fe74de/application.jwks",
"redirect_uris": [
    "https://www.raidiam.com/insurance/cb"
]
}

9.2 Open Insurance Brasil SSA Key Store e detalhes do emissor

As links a seguir apontam para as chaves públicas do Diretório de Participantes, e devem ser usadas para verificar a validadade da assinatura dos software_statements apresentados durante o processo de registro de cliente.

Producão

https://keystore.directory.opinbrasil.com.br/openinsurance.jwks

Emissor do Open Insurance Open Insurance Brasil SSA de produção

Sandbox

https://keystore.sandbox.directory.opinbrasil.com.br/openinsurance.jwks

Emissor do Open Insurance Open Insurance Brasil SSA de sandbox

9.3 Sobre os mecanismos de autenticação e autorização dos serviços de DCR e DCM

Por serem serviços auxiliares ao fluxo principal do Open Insurance Brasil, os serviços de registro e manutenção dinâmica de clientes não utilizam os mesmos mecanismos de controle de acesso. Por exemplo: não é possível exigir um access_token OAuth 2.0 de uma aplicação cliente que ainda não está registrada na instituição transmissora. Para estender as RFC7591 e RFC7592, que recomendam mecanismos mínimos para autenticação dos seus serviços, as instituições que suportam os fluxos de registro e manutenção dinâmica de clientes devem implementar em seus Servidores de Autorização os controles a seguir:

9.3.1 Registro de cliente - POST /register

validar que o certificado apresentado pela aplicação cliente é subordinado às cadeias do ICP-Brasil definidas no Padrão de Certificados do Open Insurance Brasil;
assegurar que a assinatura do software_statement apresentado pela aplicação cliente durante o registro tenha sido feita pelo Diretório de Participantes através das chaves públicas descritas na seção anterior;
assegurar que o software_statement apresentado pela aplicação cliente durante o registro corresponda à mesma instituição do certificado de cliente apresentado, validando-o através dos atributos que trazem organization_id no certificado X.509.
emitir, na resposta do registro, um registration_access_token para ser usado como token de autenticação nas operações de manutenção da aplicação cliente registrada, seguindo as especificações descritas na RFC7592.
não devem ser permitidos múltiplos cadastros DCR para o mesmo Software Statement, de forma que em caso de tentativa de novo registro para um Software Statement já cadastrado, deve se utilizar o procedimento de Error Response definido no item 3.2.2 da RFC7591.

9.3.2 Manutenção de cliente - GET /register - PUT /register - DELETE /register

validar que o certificado apresentado pela aplicação cliente é subordinado às cadeias do ICP-Brasil definidas no Padrão de Certificados do Open Insurance Brasil;
validar a presença e a correspondência do header Bearer Authorization contendo o valor do atributo registration_access_token retornado durante o registro do cliente correspondente.

Observação: A RFC7592 prevê a possibilidade de rotação do registration_access_token emitido pelo Servidor de Autorização a cada uso, tornando-o um token de uso único. As instituições devem considerar esse aspecto no registro de suas aplicações cliente para receber e atualizar o registration_access_token pelo novo valor recebido nas chamadas de manutenção de cliente.

FAPI Security Profile 1.0

O Open Insurance adere ao padrão do Open Finance Brasil grade API Security Profile 1.0 Implementers Draft 3.

Padrão de Certificados

Prefácio

Objetivo

Especificar o conjunto de certificados necessários que devem ser utilizados pelas entidades participantes do Open Insurance Brasil para garantir interoperabilidade para autenticação, confidencialidade, integridade e não repúdio entre os participantes, bem como para os usuários e consumidores destas entidades. O público desta especificação são entidades participantes do Open Insurance Brasil que necessitam fazer a emissão de certificados para se autenticar junto a outras entidades, bem como oferecer a seus clientes um canal de autenticação seguro.

Convenções Notacionais

"deve" => equivalente ao termo "shall" e expressa um requerimento definido no documento (nas traduções é similar ao termo "must", que pode denotar um requerimento externo ao documento);
"não deve" => equivalente ao termo "shall not" e também expressa um requerimento definido no documento;
"deveria" e "não deveria"=> equivalente ao termo "should" e "should not" e expressa uma recomendação
"pode" => equivalente ao termo "may" indica uma permissão

1. Escopo

Este documento especifica os tipos de certificados necessários para:

Autenticar mutuamente (MTLS - Mutual TLS) as aplicações dos participantes;
Assinatura de Mensagens (JWS - JSON Web Signature) de aplicações para garantir a autenticidade e não repúdio de mensagens entre os participantes;
Apresentar um canal seguro e confiável para clientes do Open Insurance Brasil;
Autenticar participantes no Diretório de participantes do Open Insurance Brasil.

2. Referências Normativas

ISODIR2 - ISO/IEC Directives Part 2
RFC5280 - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
RFC7519 - JSON Web Token (JWT)
RFC7515 - JSON Web Signature (JWS)
RFC7591 - OAuth 2.0 Dynamic Client Registration Protocol
RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol
BCP195 - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)
RFC8705 - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens
OFB-FAPI - Open Finance Brasil Financial-grade API Security Profile 1.0
OPIN-FAPI-DCR - Open Insurance Brasil Financial-grade API Dynamic Client Registration Profile 1.0
DOC-ICP-01 - DECLARAÇÃO DE PRÁTICAS DE CERTIFICAÇÃO DA AUTORIDADE CERTIFICADORA RAIZ DA ICP-BRASIL
RFC6749 - The OAuth 2.0 Authorization Framework
RFC2818 - HTTP Over TLS
RFC5246 - The Transport Layer Security (TLS) Protocol Version 1.2

3. Termos e Definições

Para o propósito deste documento os termos definidos na RFC5280, BCP195, RFC8705, e ISO29100 são aplicáveis.

4. Glossário

API – Application Programming Interface
DCR – Dynamic Client Registration
HTTP – Hyper Text Transfer Protocol
ICP - Infraestrutura de Chave Públicas Brasileira
SS – Software Statement
SSA – Software Statement Assertion
TLS – Transport Layer Security
mTLS – Mutual Transport Layer Security

5. Padrão de Certificados Open Insurance Brasil

5.1 Introdução

O ecossistema do Open Insurance Brasil faz uso de cadeias de certificados e protocolo TLS para garantir a confidencialidade, autenticação e integridade do canal de comunicação utilizado pelas APIs das instituições participantes, bem como dos clientes de cada um dos participantes.

Os certificados utilizados pelo Open Insurance Brasil também são necessários para autenticar as aplicações através do oAuth 2.0 mTLS ou private_key_jwt, além de também servirem para realizar a assinatura de payloads pelo uso de JWS. Outra atribuição importante dos certificados é autenticar e apresentar um canal seguro para o usuário final no ato de autenticação e uso dos serviços prestados pela entidade participante.

5.2 Certificados ICP-Brasil

Os certificados emitidos pelas Autoridades Certificadoras autorizadas pelo ICP-Brasil são utilizados apenas na comunicação entre as entidades participantes do ecossistema do Open Insurance Brasil.

Os processos de emissão e revogação dos certificados são de responsabilidade das próprias Autoridades Certificadores, sendo regulamentados por Declarações de Prática de Certificação, e supervisionadas pelo Comitê Gestor da Infraestrutura de Chaves Públicas Brasileira.

As práticas, processos, disponibilização e valores praticados pelas Autoridades Certificadoras não são de responsabilidade do Estrutura Inicial do Open Insurance Brasil.

Algoritmos

Todos os certificados emitidos junto ao ICP-Brasil devem possuir as seguintes características:

Tipo A do ICP-Brasil;
Algoritmo de Chaves: RSA 2048 bits;
Message Digest: SHA 256 bits.

5.2.1 Certificado Servidor

O Certificado Servidor deve ser emitido para proteger e autenticar o canal TLS utilizado pelas APIs que serão consumidas pelas aplicações cliente de entidades participantes do Open Insurance.

O padrão de certificado utilizado deve seguir as práticas de emissão de certificados existentes de "CERTIFICADO PARA SERVIDOR WEB – ICP-Brasil".

O certificado de servidor precisa ser enviado com a cadeia intermediária, conforme RFC5246 (itens 7.4.2).

5.2.2 Certificado Cliente

Os Certificados de Aplicação Cliente (Transporte) são utilizados para autenticar o canal mTLS e para realizar a autenticação da aplicação cliente através de oAuth2.0 mTLS ou private_key_jwt, de acordo com o cadastro da aplicação realizado pelo processo de Dynamic Client Registration junto à entidade transmissora. Sobre o mTLS, o certificado cliente precisa ser enviado com a cadeia intermediária, conforme RFC5246 (itens 7.4.2 e 7.4.6).

Para emissão de Certificado Cliente é necessário que a instituição participante do Open Insurance Brasil tenha realizado o cadastro da aplicação no Serviço de Diretório, através do processo de emissão de Software Statement Assertion, e com isso já tenha obtido o valor de Software Statement ID.

5.2.2.1 Atributos Open Insurance Brasil

serialNumber: Cadastro Nacional de Pessoal Jurídica (CNPJ) da pessoa jurídica titular do certificado e associado ao atributo UID e Software Statement ID, durante validação junto ao Serviço de Diretório do Open Insurance Brasil;
organizationIdentifier: Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil;
UID: Software Statement ID cadastrado no Serviço de Diretório do Open Insurance Brasil e pertencente ao CNPJ e Código de Participante.

O Certificado Cliente deve ser emitido através de cadeia V10, e deve obrigatoriamente conter os seguintes atributos:

Distinguished Name

businessCategory (OID 2.5.4.15): Tipo de categoria comercial, devendo conter: "Private Organization" ou "Government Entity" ou "Business Entity" ou "Non-Commercial Entity"
jurisdictionCountryName (OID: 1.3.6.1.4.1.311.60.2.1.3): BR
serialNumber (OID 2.5.4.5): CNPJ
countryName (OID 2.5.4.6): BR
organizationName (OID 2.5.4.10): Razão Social
stateOrProvinceName (OID 2.5.4.8): Unidade da federação do endereço físico do titular do certificado
localityName (OID 2.5.4.7): Cidade do endereço físico do titular
organizationIdentifier (OID 2.5.4.97): Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil e prefixo de identificação do diretório
UID (OID 0.9.2342.19200300.100.1.1): Software Statement ID gerado pelo Diretório do Open Insurance Brasil
commonName (OID 2.5.4.3): FQDN ou Wildcard

Certificate Extensions

keyUsage: critical,digitalSignature,keyEncipherment
extendedKeyUsage: clientAuth

Subject Alternative Name

dNSName: FQDN ou Wildcard

5.2.3 Certificado de Assinatura

Os Certificados de Assinatura são utilizados para realizar assinatura do payload através do uso de JWS (JSON Web Signature).

5.2.3.1 Atributos Open Insurance Brasil Presentes no Certificado

UID: Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil;
commonName: Razão Social cadastrado no Serviço de Diretório do Open Insurance Brasil e pertencente ao CNPJ e Código de Participante.

O Certificado de Assinatura deve ser emitido através de cadeia V5, e deve obrigatoriamente conter os seguintes atributos:

Distinguished Name

UID (OID 0.9.2342.19200300.100.1.1): Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Insurance Brasil
countryName (OID 2.5.4.6): BR
organizationName (OID 2.5.4.10): ICP-Brasil
organizationalUnitName (OID 2.5.4.11): Nome da Autoridade Certificadora
organizationalUnitName (OID 2.5.4.11): CNPJ da Autoridade de Registro
organizationalUnitName (OID 2.5.4.11): Tipo de identificação utilizada (presencial, videoconferência ou certificado digital)
commonName (OID 2.5.4.3): Nome da Razão Social

Certificate Extensions

keyUsage: critical,digitalSignature,nonRepudiation

Subject Alternative Name

otherName (OID 2.16.76.1.3.2 – ICP-Brasil): Nome do responsável pelo certificado
otherName (OID 2.16.76.1.3.3 – ICP-Brasil): Cadastro Nacional de Pessoa Jurídica (CNPJ) da pessoa jurídica titular do certificado;
otherName (OID 2.16.76.1.3.4 – ICP-Brasil): Responsável pelo certificado de pessoa jurídica titular do certificado (data de nascimento, CPF, PIS/PASEP/CI, RG);
otherName (OID 2.16.76.1.3.7 – ICP-Brasil): Número do Cadastro Especifico do INSS (CEI) da pessoa jurídica titular do certificado.

5.2.3.2 Autoridades Certificadoras Participantes

As seguintes autoridades certificadoras realizaram o processo de onboarding ao Open Insurance Brasil e estão habilitadas para realizar a emissão de certificados do Open Insurance Brasil utilizando para tal os certificados nível 1 aqui listados:

CertiSign
- Cadeia ICP V5, Impressão Digital SHA256: 94:EB:D7:63:DC:D3:9A:85:87:48:D1:43:38:54:F7:D4:72:B1:DD:47:DD:D2:70:43:23:6F:83:80:2F:AA:F1:AB
- Cadeia ICP V10, Impressão Digital SHA256: 59:6D:25:3B:A2:BE:B7:F1:66:C4:F5:8D:08:78:FB:28:2E:30:8A:28:2C:41:62:69:40:18:BE:5A:17:49:74:19
- Cadeia ICP V10, Impressão Digital SHA256: 55:A4:89:F6:0F:78:5B:EB:E0:42:E9:9A:69:AC:8E:C3:3C:9F:17:37:4C:C4:B7:66:F6:04:CF:70:79:EA:09:BA
Serasa
- Cadeia ICP V5, Impressão Digital SHA256: 48:E3:35:02:C1:11:39:41:03:20:0A:6F:BB:7D:91:7B:C0:2B:9B:24:41:54:5A:23:0F:B0:B7:FD:37:85:DF:5E
- Cadeia ICP V10, Impressão Digital SHA256: 50:D0:E2:8B:7B:1A:13:CB:2D:E7:BF:F8:12:A9:3B:74:BE:D4:C5:07:FD:4A:06:20:E6:B6:D8:8E:F6:76:10:53
- Cadeia ICP V10, Impressão Digital SHA256: 95:E0:F8:9A:8E:0E:12:E3:E4:1D:6D:5A:AB:44:72:D7:32:1C:2E:BC:D9:29:0E:78:D6:16:97:CD:F5:D4:3D:66
Serpro
- Cadeia ICP V5, Impressão Digital SHA256: 35:33:05:81:E9:22:4B:72:CB:34:0F:A4:4B:8F:57:DA:79:AC:0A:3C:95:16:0C:BD:45:19:EC:C1:1B:AB:5C:12
- Cadeia ICP V10, Impressão Digital SHA256: 08:FC:94:2D:51:76:E5:68:AC:BE:F9:C5:95:F3:6A:20:DE:6A:CF:9E:A3:0C:6F:5F:CE:DD:48:21:6E:D5:B0:70
Soluti
- Cadeia ICP V5, Impressão Digital SHA256: 86:D4:58:36:5C:FA:BF:FA:E4:54:2A:B9:8B:99:39:0F:51:9E:C9:D8:31:81:2B:53:00:45:C4:12:AE:6E:B5:B6
- Cadeia ICP V10, Impressão Digital SHA256: 16:9C:BF:05:47:F3:DF:C4:E6:3E:4A:F9:E0:25:5A:76:03:77:78:FF:5B:8F:4A:53:6A:BD:FF:3A:91:DF:C3:C5
Valid
- Cadeia ICP V5, Impressão Digital SHA256: 40:8E:1F:56:1F:96:4E:95:5F:33:8B:94:18:95:E5:20:D1:C7:5A:18:2C:91:63:FA:84:BA:94:BB:5C:3D:A6:E6
- Cadeia ICP V10, Impressão Digital SHA256: AD:96:0D:6A:51:AF:58:E1:EC:09:EE:05:E6:DF:82:7A:77:18:37:9C:AB:F0:A5:52:9D:E4:B0:1C:12:29:08:C0

5.2.4 Certificado para Front-End

Os certificados para Front-End são utilizados para disponibilizar serviços, em geral páginas Web, com uso de TLS, que são acessados pelo usuário final. Dado a sua finalidade, e para garantir maior interoperabilidade, os certificados devem ser do tipo EV (Extended Validation) e devem ser ser gerados através de uma autoridade certificadora válida, seguindo as regras definidas na RFC 5280 e RFC 2818, em conformidade com os princípios e critérios WebTrust.

Apêndice

Modelo de Configuração de Certificado Cliente - OpenSSL

[req]
oid_section = OIDs

default_bits = 2048
default_md = sha256
encrypt_key = yes
prompt = no
string_mask = utf8only
distinguished_name = client_distinguished_name
req_extensions = req_cert_extensions

[ OIDs ]
organizationIdentifier = 2.5.4.97

[ client_distinguished_name ]
businessCategory = <tipo de organização>
jurisdictionCountryName = BR
serialNumber = <CNPJ>
countryName = BR
organizationName = <Razão Social>
stateOrProvinceName = <UF>
localityName = <Cidade>
organizationIdentifier = OPIBR-<Código de Participante>
UID = <Software Statement ID emitido pelo diretório>
commonName = <FQDN|Wildcard>

[ req_cert_extensions ]
basicConstraints = CA:FALSE
subjectAltName = @alt_name
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = clientAuth

[ alt_name ]
DNS = <FQDN|Wildcard>

Modelo de Configuração de Certificado de Assinatura - OpenSSL

[req]
default_bits = 2048
default_md = sha256
encrypt_key = yes
prompt = no
string_mask = utf8only
distinguished_name = client_distinguished_name
req_extensions = req_cert_extensions

[ client_distinguished_name ]
UID = <Código de Participante>
countryName = BR
organizationName = ICP-Brasil
0.organizationalUnitName = <Certificate Authority>
1.organizationalUnitName = <CNPJ da Registration Authority>
2.organizationalUnitName = <Validation type>
commonName = <Company Name>

[ req_cert_extensions ]
basicConstraints = CA:FALSE
subjectAltName = @alt_name
keyUsage = critical,digitalSignature,nonRepudiation

[ alt_name ]
otherName.0 = 2.16.76.1.3.2;UTF8:<Name of the person responsible for the organization>
otherName.1 = 2.16.76.1.3.3;UTF8:<CNPJ>
otherName.2 = 2.16.76.1.3.4;UTF8:<CPF/PIS/RF of responsible person>
otherName.3 = 2.16.76.1.3.7;UTF8:<INSS Number>

Tabela com Endpoints vs Tipo de Certificado e mTLS

Abaixo apresentamos quais endpoints podem ser publicados utilizando certificado EV como autenticação do consentimento e os endpoints de autenticação de APIs privadas/negócios que devem ser publicadas usando certificado ICP. Você também poderá verificar quais endpoints devem proteger suas conexões utilizando mTLS.

Fica a critério da instituição a escolha do certificado que deve ser adotado para os endpoints da Fase 1, os quais, por natureza, são de acesso público.

Fase	Grupo	APIs (em construção)	Certificado	mTLS
NA	OIDC	.well-known/openid-configuration	EV ou ICP WEB SSL
NA	OIDC	jwks_uri	EV ou ICP WEB SSL
NA	OIDC	authorization_endpoint	EV
NA	OIDC	token_endpoint	ICP WEB SSL	Obrigatório
NA	OIDC	userinfo_endpoint	ICP WEB SSL	Obrigatório
NA	OIDC	pushed_authorization_request_endpoint	ICP WEB SSL	Obrigatório
NA	DCR	registration_endpoint	ICP WEB SSL	Obrigatório
NA	OIDC	revocation_endpoint	ICP WEB SSL	Obrigatório
2	Consentimentos	/consents/*	ICP WEB SSL	Obrigatório
2	Resources	/resources/*	ICP WEB SSL	Obrigatório
2	Dados	/customers/*	ICP WEB SSL	Obrigatório
2	Transacionais	/insurance-/	ICP WEB SSL	Obrigatório

Assinaturas

Sobre os certificados exigidos para assinatura de mensagens: Padrões de certificados digitais Open Insurance Brasil

Sobre os algoritmos usados para assinatura de mensagens JWS: Perfil de segurança FAPI - Open Banking Brasil

Sobre mensagens assinadas, JWS e JWKS: Guia do Usuário para Instituições Receptores de Dados

Glossário de Segurança

Sigla	Descrição	Informação
API	Interface de programação de aplicativo	Uma interface de programação de aplicativo é um conjunto de rotinas, protocolos e ferramentas para construir aplicativos de software. Uma API especifica como os componentes de software devem interagir
FAPI	Financial API	Especificação técnica de API e define requisitos técnicos adicionais para o setor financeiro
CIBA	Client Initiated Backchannel Authentication	A autenticação de backchannel iniciada pelo cliente (CIBA) é um dos padrões mais recentes da OpenID Foundation. São categorizados como "fluxo desacoplado". Permite novas maneiras de obter o consentimento do usuário final
OAuth		O OAuth é um protocolo de autorização para APIs web voltado a permitir que aplicações client acessem um recurso protegido em nome de um usuário
OIDC	OpenID Connect	OpenID Connect é um protocolo de identidade simples com padrão aberto
JWT	JSON Web Token	Uma técnica definida na RFC 7519 para autenticação remota entre duas partes. Ele é uma das formas mais utilizadas para autenticar usuários em APIs RESTful
JWS	JSON Web Signature	Uma forma de garantir a integridade das informações em um formato altamente serializado
SHA256	Secure Hash Algorithm	Um conjunto de funções criptográficas de hash
PKCE	Proof Key for Code Exchange	Chave de prova para troca de código por clientes públicos Oauth
MAC	Código de Autenticação de Mensagem	Permite que as declarações sejam assinadas digitalmente ou protegidas por integridade utilizando JWS
ICP-Brasil	Infraestrutura de Chaves Públicas Brasileira	Na definição oficial, “uma cadeia hierárquica de confiança que viabiliza a emissão de certificados digitais para identificação virtual do cidadão"
AC	Autoridade Certificadora
AR	Autoridade de Registro
TLS	Transport Layer Security
ECDSA	Elliptic Curve Digital Signature Algorithm	Algoritmo de método de assinatura digital de documentos utilizando criptografia baseada em curvas elípticas
ECDHE	Elliptic-curve Diffie–Hellman	Protocolo de contrato chave que permite que duas partes, cada uma com um par de chaves público-privado de curva elíptica, estabeleçam um segredo compartilhado em um canal inseguro
AES	Advanced Encryption Standard	Algoritmos de criptografia de bloco simétrico com uma chave de criptografia de 256 bits
Autenticação mútua		Chamamos de autenticação mútua quando ambos cliente e servidor apresentam certificados para serem validados pelo par
CSR	Certificate Signing Request	Contém informação que irá ser incluída no seu certificado como o nome da empresa/organização, common name (domínio), localidade e país. Também contém a chave pública (public key) que será incluída no seu certificado. Normalmente é também criada uma chave privada (private key) ao mesmo tempo que é criado o CSR
SSA	Software Statement Assertion	SSA é um JSON Web Token (JWT) que contém metadados sobre uma instância de aplicativo client desenvolvida por um TPP. O JWT é emitido e assinado pelo Diretório do Open Insurance Brasil
End User		Identificação de usuário final que possui as informações que se deseja acessar
Back-End		Aplicação ou código que da inteligência de negocio as ações solicitadas via API , código que efetivamente realiza a função desejada
Json	JavaScript Object Notation	Modelo para armazenamento e transmissão de informações no formato texto.
Claims		Escopos/declarações usadas em uma API durante a autenticação para autorizar o acesso aos detalhes de um usuário, como nome e imagem por exemplo. Cada escopo retorna um conjunto de atributos do usuário, que são chamados de declarações
Header		Cabeçalho de uma solicitação ou resposta que transmite contexto e metadados adicionais sobre a solicitação ou resposta. Por exemplo, em uma mensagem de solicitação podem ser usados para fornecer credenciais de autenticação
Payload		Carga Útil do token JWT. É aqui que você coloca informações como a quem o token pertence, qual a expiração dele, quando ele foi criado, entre outras coisas

Referências Normativas

Referências	Descrição	Versão
JSON	The JavaScript Object Notation (JSON) Data Interchange Format: https://tools.ietf.org/html/rfc8259	Dec 2017
JWT	JSON Web Token (JWT): https://tools.ietf.org/html/rfc7519	May 2015
JWS	JSON Web Signature (JWS): https://tools.ietf.org/html/rfc7797	Feb 2016

Referências Informativas

Referências	Descrição
BCP195	Recomendações para o uso seguro do Transport Layer Security (TLS) e Datagram Transport Layer Security (DTLS): BCP 195
DOS-G	Guia de segurança sobre DDoS attacks: Denial of Service (DoS) guidance

Diretório de Participantes

Participantes Open Insurance Brasil

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Informações sobre os servidores de autorização dos participantes do Open Insurance Brasil que estão registrados no Diretório.

Base URLs:

https://data.directory.opinbrasil.com.br/participants

License: MIT

A especificação do arquivo de participantes pode ser acessada aqui.

Organisations

Recupera informações técnicas sobre Participantes registrados no diretório, essas informações permitem identificar e consumir as APIs dos participantes

Code samples

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://data.directory.opinbrasil.com.br/participants");
xhr.setRequestHeader("Accept", "application/json");

xhr.send(data);

import http.client

conn = http.client.HTTPSConnection("data.directory.opinbrasil.com.br")

headers = { 'Accept': "application/json" }

conn.request("GET", "/participants", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

HttpResponse<String> response = Unirest.get("https://data.directory.opinbrasil.com.br/participants")
  .header("Accept", "application/json")
  .asString();

GET /participants

Example responses

200 Response

[
  {
    "OrganisationId": "string",
    "Status": "Active",
    "OrganisationName": "string",
    "CreatedOn": "string",
    "LegalEntityName": "string",
    "CountryOfRegistration": "string",
    "CompanyRegister": "string",
    "RegistrationNumber": "string",
    "RegistrationId": "string",
    "RegisteredName": "string",
    "AddressLine1": "string",
    "AddressLine2": "string",
    "City": "string",
    "Postcode": "string",
    "Country": "string",
    "ParentOrganisationReference": "string",
    "Contacts": [
      {
        "ContactId": "string",
        "OrganisationId": "string",
        "ContactType": "Business",
        "FirstName": "string",
        "LastName": "string",
        "Department": "string",
        "EmailAddress": "string",
        "PhoneNumber": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "City": "string",
        "Postcode": "string",
        "Country": "string",
        "AdditionalInformation": "string",
        "PgpPublicKey": "string"
      }
    ],
    "AuthorisationServers": [
      {
        "AuthorisationServerId": "string",
        "OrganisationId": "string",
        "AutoRegistrationSupported": true,
        "ApiResources": [
          {
            "ApiResourceId": "string",
            "ApiFamilyType": "string",
            "ApiVersion": 0,
            "ApiDiscoveryEndpoints": [
              {
                "ApiDiscoveryId": "string",
                "ApiEndpoint": "http://example.com"
              }
            ]
          }
        ],
        "CustomerFriendlyDescription": "string",
        "CustomerFriendlyLogoUri": "http://example.com",
        "CustomerFriendlyName": "string",
        "DeveloperPortalUri": "http://example.com",
        "TermsOfServiceUri": "http://example.com",
        "NotificationWebhook": "http://example.com",
        "NotificationWebhookStatus": "string",
        "OpenIDDiscoveryDocument": "http://example.com",
        "PayloadSigningCertLocationUri": "http://example.com",
        "ParentAuthorisationServerId": "string"
      }
    ],
    "OrgDomainClaims": [
      {
        "OrganisationAuthorityDomainClaimId": "string",
        "AuthorisationDomainName": "string",
        "AuthorityId": "string",
        "AuthorityName": "string",
        "RegistrationId": "string",
        "Status": "Active"
      }
    ],
    "OrgDomainRoleClaims": [
      {
        "OrganisationId": "string",
        "OrganisationAuthorityClaimId": "string",
        "AuthorityId": "string",
        "Status": "Active",
        "AuthorisationDomain": "string",
        "Role": "string",
        "Authorisations": [
          {
            "Status": "Active",
            "MemberState": "st"
          }
        ],
        "RegistrationId": "string",
        "UniqueTechnicalIdenifier": [
          "string"
        ]
      }
    ]
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Export the open-data for all the organisations	OrganisationsExportOpenData
401	Unauthorized	Unauthorized	None
403	Forbidden	Forbidden	None
404	Not Found	The specified key does not exist	None
500	Internal Server Error	Internal Server Error	None
502	Bad Gateway	Bad Gateway	None

Especificações de APIs Diretório

O Diretório Central do Open Insurance Brasil pode ser acessado tanto via interface gráfica quanto por meio de integração por APIs.

Para acessar as APIs do Diretório, verifique os manuais para criação de certificados.

Criando uma Declaração de Software

Gerando o Certificado BRCAC

Gerando o Certificado BRSEAL

Obtendo um token para acesso as APIs do Diretório

Para entender como usar cada API, leia a especificação do Swagger da API do Diretório disponível nesse link.

Guia de operação do diretório central

1. Introdução

O Open Insurance, ou Sistema de Seguros Aberto, é a possibilidade de consumidores de produtos e serviços de seguros, previdência complementar aberta e capitalização permitirem o compartilhamento de suas informações entre diferentes sociedades autorizadas/credenciadas pela SUSEP de forma segura, ágil, precisa e conveniente. Para entregar esses benefícios ao consumidor, o Open Insurance operacionaliza e padroniza o compartilhamento de dados e serviços por meio de abertura e integração de sistemas, com privacidade e segurança. Acesse o site oficial da SUSEP

Antes de Começar

Esse guia tem como objetivo demonstrar, de forma prática, a operação do Diretório Central do Open Insurance Brasil. Além disso, ele é complementar a outras documentações disponibilizadas pela governança e não faz parte do escopo quaisquer detalhamentos relacionados à experiência do usuário e desenvolvedor, definições de segurança e especificação de APIs. Todas as funcionalidades estão disponíveis em sandbox e podem ser testadas em: https://web.sandbox.directory.opinbrasil.com.br/. Procedimentos em produção pendentes serão disponibilizados assim que possível. As ações aqui apresentadas podem ser realizadas tanto por administradores quanto por contatos técnicos primários e secundários. Para ilustrar este guia e tentar deixar as situações de uso mais palpáveis, foram criadas instituições e telas fictícias.

As instituições e marcas não são reais.
As telas desenvolvidas, os softwares e sites são meramente ilustrativos, para que seja possível ver um exemplo de como os requisitos e as recomendações podem ser aplicados em situações de uso real.
Nomenclaturas e imagens ilustrativas estão descritas na língua inglesa, devido sua ampla abrangência e por conter terminologia técnica que, em algumas situações, não dispõe de tradução literal. O ajuste do idioma no Diretório fica a critério do usuário, podendo ser ajustado a qualquer momento.

Tipos de Usuários

Neste exemplo, mostramos as diversas possibilidades suportadas de atribuições de função para um usuário cadastrado no Diretório.


	Administrativo	Usuários com poderes de administração no Diretório, podendo realizar todas ações.
	Operação	Usuários com permissão em ferramentas específicas no Diretório.
	Plataforma	Usuários para gestão e operação das plataformas do ecossistema, como o Service Desk, Portal, Plataforma de Resolução de Disputas e Plataforma Centralizada (Ressarcimento).

Relação Organização vs. Marcas

Neste exemplo, mostramos as diversas possibilidades suportadas para se realizar cadastros de organizações no Diretório. Assim, uma organização pode ser cadastrada de forma independente ou pertencente a um conglomerado. Já as marcas são uma forma mais amigável, democrática e fácil para identificação das instituições participantes. Uma Marca de um conglomerado pode estar correlacionada a mais de uma Instituição Participante, assim como uma Instituição Participante pode estar correlacionada a mais de uma marca.

Importante: a Marca cadastrada no diretório será a mesma apresentada para escolha do usuário na Jornada de Compartilhamento de Dados e Iniciação de Pagamentos. As Instituições Participantes (ou organizações) também serão apresentadas em tela, apenas em caráter informativo. Para maiores detalhes, consulte o Guia de Experiência do Usuário.

Pontos de atenção no cadastramento de marca/authorisation server

Uma marca é representada por um Authorisation Server e o mesmo sempre deve ser cadastrado associado a uma organização.
O vinculo entre uma organização master (mãe) e uma organização que pertence ao conglomerado é realizado via preenchimento do campo Parent Organization Reference ID no cadastro da organização filha, informando o CNPJ da organização mãe (caso seja necessário ajuste, favor entrar em contato via Service Desk em https://servicedesk.opinbrasil.com.br/servicePortal).
Quando a estrutura for de um conglomerado (uma organização master e uma ou mais organizações relacionadas) é recomendado o cadastro da marca na instituição mãe, caso as filhas venham a utilizar somente a mesma marca e arquitetura de autenticação. Importante ressaltar que, caso não seja cadastrada uma marca exclusiva para o organização filha, a mesma irá herdar a(s) marca(s) da organização mãe.
Caso uma marca pertença a uma organização filha, o cadastro deve ser exclusivamente realizado na filha.
Caso a mesma marca pertença a mais de uma organização, deve ser realizado um cadastro de Authorisation Servers para cada uma das organizações. É recomendado que as configurações dos Authorisation Servers sejam iguais, principalmente o campo Customer Friendly Server Name (marca).
Quando for necessário cadastrar uma marca exclusiva para uma organização filha, ela deixa de herdar a(s) marca(s) da organização mãe. Caso uma filha tenha que estar relacionada a uma marca exclusiva e também a da mãe, é necessário cadastrar a marca da mãe na filha.

Alternativas para atualização da marca


API Participants	Prefira por consumir dados da API Participants. Ela permite que o conteúdo seja fornecido ao usuário através de um servidor mais próximo, acelerando a distribuição e melhorando a experiência de consumo.
Webhook do Diretório	Inscreva-se no webhook do Diretório para receber os eventos de notificação das principais atualizações, como alteração de cadastro, atualização de marca, entre outros.
Cache local	Alguns participantes optam pela utilização de estruturas de cache local. Assim, recomenda-se a revalidação diária dos dados, de modo a mantê-los íntegros e com a versão mais recente possível.


	Importante! Caso a instituição queira utilizar alguma chave forte, recomendamos utilizar o AuthorisationServerID. Os campos Customer Friendly Server Name e Description são especialmente suscetíveis a atualizações pelas organizações e não devem ser utilizados para esse fim.

Cadastramento Fase 1 x Fase 2

Se o cadastramento do Authorisation Server na Fase 1 já foi realizado com uma marca válida para a Fase 2, é necessário cadastrar os recursos de Fase 2 no mesmo Authorisation Server, mantendo o Customer Friendly Server Name (marca) da Fase 1.
Se o cadastramento do Authorisation Server na Fase 1 não foi realizado com uma marca válida para a Fase 2: é necessário atualizar o Customer Friendly Server Name (marca) para a Fase 2 e cadastrar os recursos de Fase 2 no mesmo.
Os recursos da Fase 1 devem estar declarados em pelo menos um Authorisation Server do participante válido para a Fase 2.
Após esse processo, caso a instituição venha a ter Authorisation Servers / marcas oferecendo recursos exclusivos de fase 2, recomenda-se a criação de novos registros sem os recursos de Fase 1.

2. Registrando um usuário no diretório

Para acessar o Diretório de participantes você precisa estar registrado com um usuário válido. Esta seção descreve as etapas necessárias para realizar o registro de um novo usuário.

ETAPA 1: Registrando um usuário no Diretório

Requisitos

No navegador, digite a URL de acordo com o ambiente a ser acessado:

Sandbox: https://web.sandbox.directory.opinbrasil.com.br/

Produção: https://web.directory.opinbrasil.com.br/
Clique no link Register
Na tela Register for an account, preencha os campos do formulário.
Clique no botão Register

Nota: E-mails sociais não são permitidos. Você deve utilizar um endereço de e-mail válido da instituição. O cadastro pode ser realizado por qualquer colaborador da organização, identificado aqui como um Iniciador de Cadastro, podendo esse ser tanto um contato administrativo quanto técnico da instituição.

Nome do campo	Descrição	Exemplo
First Name	Deve ser preenchido com o primeiro nome do usuário.	Maria
Family Name	Deve ser preenchido com o sobrenome do usuário.	Gomes
E-mail Address	Deve ser informado um endereço de e-mail corporativo.	maria.gomes@semicredi.com.br
Phone Number	Informar o número de telefone de contato do usuário.	+55 11 900000000
Password	Definir uma senha que deve conter entre 8 e 24 caracteres com letras maiúsculas, minúsculas, números e ao menos um carácter especial.	<senha_secreta>
Confirm Password	Repetir a mesma senha informada no campo anterior.	<senha_secreta>
National ID (CPF)	Informar o número de registro do Cadastro de Pessoa Física (CPF).	999999999-00
Do you possess an e-signature certificate?	O seletor deve estar assinalado caso o usuário possua um eCPF

ETAPA 2: Verificando os dados informados

Requisitos

Nesta etapa, o Diretório irá enviar uma senha de uso único (OTP), que será encaminhada ao endereço de e-mail e número de telefone informado na etapa anterior.
No e-mail recebido, selecione, copie e cole o código OTP no campo EMAIL VERIFICATION CODE.
Na mensagem SMS recebida no telefone celular, copie o código OTP e informe no campo PHONE NUMBER VERIFICATION CODE.
Clique no botão Verify.

Nota: Caso você não tenha recebido o e-mail com o código de confirmação, verifique sua caixa de SPAM e as políticas de bloqueio de mensagens. O envio das mensagens poderá sofrer algum atraso. Contudo, se o problema persistir, clique no botão Resend OTP para reenvio das mensagens.

ETAPA 3: Confirmando o progresso de registro

Requisitos

Nesta etapa, faça o download de um aplicativo de autenticação de sua preferência. É possível utilizar o Google Authenticator, Microsoft Authenticator, LastPass Authenticator, 1Password entre outros.
Digitalize o QR Code que aparece na página e no aplicativo de autenticação. Copie e cole a senha de uso único (OTP).
Clique no botão Sign-In.

ETAPA 4: Confirmação da assinatura eletrônica

Requisitos

Nesta etapa, será enviado um e-mail contendo um link para análise e assinatura do Termo de Aceite.
Selecione e copie o código de acesso apresentado na janela Upload e-signature confirmation.
Na mensagem recebida na caixa de entrada em nome da DocuSign, clique no link ANALISAR DOCUMENTO. Ao clicar, você será redirecionado para o website da DocuSign.
No navegador, cole o valor copiado no passo 2 no campo Código de acesso.
Clique no botão Validar.

ETAPA 5: Análise e confirmação do Termo de Aceite

Requisitos

Nesta etapa, no website da DocuSign, clique no botão Continuar.
Role o documento para baixo e, na página seguinte, clique no ícone Rubricar. No final das páginas, clique no ícone Assinar.
Clique no botão Concluir.
Na janela "Salvar uma cópia do seu documento", você pode se inscrever para obter uma conta DocuSign gratuita e assinar todos os seus documentos eletronicamente. Nesta janela, também é possível clicar no ícone Fazer Download e baixar uma cópia do documento assinado.
Clique no botão Submeter. Ao clicar no botão Submeter, você aceita os Termos e Condições e reconhece que seus dados serão utilizados conforme descrito na Política de Privacidade da DocuSign.
Na caixa de entrada, você receberá um e-mail enviado pela DocuSign contendo uma cópia do documento Termo de Aceite assinado eletronicamente.
Retorne ao Diretório e, na janela Upload esignature confirmation, clique no botão Check status. Se todas as etapas anteriores forem validadas com sucesso, você será automaticamente redirecionado à página inicial do Diretório.

3. Acessando uma Organisation

Esta seção descreve as etapas necessárias para exibir detalhes de uma organização.

ETAPA 1: Exibindo detalhes de uma organização

Requisitos

No Diretório, localize e selecione a sua organização.
Revise as informações previamente cadastradas.

Nota: Os cadastrados foram realizados de forma antecipada a partir de informações fornecidas junto a SUSEP. É fundamental que as organizações verifiquem as informações cadastradas. Caso exista alguma divergência, entre em contato pelo e-mail secretariado@opinbrasil.com.br .

Nome do campo	Descrição	Exemplo
Status	Define o estado atual do cadastro, se está ativo ou não.	Active
Organisation Name	Deve ser informado o nome da organização.	Seg. Semicredi S.A.
Registration Number-CNPJ	Deve ser informado o número de Cadastro Nacional da Pessoa Jurídica (CNPJ) da organização.	22.222.222/0002-22
Date of Creation	Data de criação do registro de cadastro da organização.	2021-01-07T11:13:08.531Z
Company Registrar		Cadastro Nacional da Pessoa Jurídica
Organisation ID	Identificador da organização. Esta informação será gerada automaticamente.	cdc674fd-b019-5110-af5d-0268ed8227371
Parent Organisation Reference ID	Deve ser informado o número de Cadastro Nacional da Pessoa Jurídica (CNPJ) da organização mãe para casos em que seja necessária a constituição de um conglomerado. A seção de Cadastramento de conglomerados ilustra este cenário em mais detalhes.	11.111.111/0001-11
Legal Name	Deve ser informado o nome legal de cadastro da instituição.	Seguradora Semicredi S.A.
Address Line 1	Deve ser informado o logradouro da organização.	Rua ABC 123
Address Line 2	Deve ser informado o logradouro da organização.	Cidades Monções
City	Deve ser informada a cidade da organização.	São Paulo, SP
Country	Deve ser informado o país da organização.	BR

Cadastramento de Conglomerado

No diretório de participantes há o conceito de conglomerado. Assim, uma organização mãe poderá ser referenciada em um cadastro de uma organização filha atribuindo-se o CNPJ da organização mãe no campo PARENT ORGANISATION REFERENCE ID da organização filha.

Importante: se a sua organização faz parte de um conglomerado, é fundamental referenciar as organizações filhas com a organização mãe.

4. Cadastrando contatos

Após o onboarding da instituição e do representante da mesma, é necessário realizar o cadastro da equipe de contatos de notificação no Diretório Central. Esses contatos são para possíveis comunicações entre os participantes e a estrutura central.

ETAPA 1: Cadastrando um novo contato

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Contacts e clique no botão New Contact.
Na janela New Contact preencha os campos do formulário. A tabela a seguir apresenta cada um dos campos em mais detalhes.
Clique no botão Save.

Nota: Os usuários de notificação não possuem ações dentro do Diretório e nas demais plataformas do perímetro central.

Nome do campo	Descrição	Exemplo
Contact Type*	Tipo do contato (Business/Negócio, Technical/Técnico, Billing/Cobrança, Incident/Incidente e Security/Segurança).	Incident
Department	Deve ser informado o departamento do contato.	Operações de TI
First Name	Deve ser informado o primeiro nome do contato.	Maria
Last Name	Deve ser informado o sobrenome do contato.	Gomes
E-mail*	O endereço de e-mail do contato.	maria.gomes@semicredi.com.br
Phone Number*	Deve ser informado o número de telefone do contato.	+55 51 900000000
Additional Information	Deve ser informado o e-mail para o grupo de notificação do contato.	openinsurance@semicredi.com.br
PGP Public Key	Deve ser preenchido com uma chave alfanumérica para comunicação de dados de incidentes de segurança entre instituições.	Como esta chave tem extensão muito grande para adicionar como exemplo, segue link para documentações para documentações que definem a chave PGP (RFC 488).
Address Line 1	Deve ser informado o endereço (Rua, Avenida ou Alameda).	Rua ABC 123
Address Line 2	Deve ser informado o bairro.	Cidades Monções
City	Deve ser informado a cidade de domicílio.	São Paulo
Post Code	Deve ser informado o código portal.	99.999-99
Country	Deve ser informado o país de domicílio.	Brasil

(*) Campo obrigatório

DETALHAMENTO DOS TIPOS DE CONTATO

Nome do campo	Descrição
Business/Negócio	Contato responsável pela gestão de negócio do Open Insurance na instituição.
Technical/Técnico	Contato para tratativa de problemas técnicos de performance, disponibilidade e em relação a APIs de forma geral.
Billing/Cobrança	Contato responsável pela cobrança dos custos da estrutura central do Open Insurance Brasil.
Incident/Incidente	Contato responsável pelo atendimento de incidentes relacionados ao Open Insurance na instituição.
Security/Segurança	Contato para tratativas relacionadas a problemas de caráter de segurança como DCR, certificados, entre outros.

Nota: É de inteira responsabilidade da instituição manter os contatos sempre atualizados para que a comunicação entre as instituições participantes não seja prejudicada.

5. Cadastrando reivindicações de domínio de autoridade

Esta seção explica as etapas para cadastrar reivindicações de domínio de autoridade.

ETAPA 1: Cadastrando uma nova reivindicação de domínio

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Authority Domain Claims e clique no botão New Domain Claim.
Na janela New Authority Domain Claim preencha os campos do formulário. A seguir serão apresentados maiores detalhes sobre os campos.
Clique no botão Save.

Nome do campo	Descrição	Exemplo
Authority Name*	Informe o nome da autoridade.	Seguradora Semicredi
Authorisation Domain Name*	Informe o nome de domínio de autorização.	Open Insurance Brasil
Authority ID	Exibe o identificador de autoridade única. Esta informação será gerada automaticamente.	5360d5bf-5024-47cd-bd18-daab08df38ba
Registration ID	ID de registro de reivindicação de domínio exclusivo. Não é necessário preencher esta informação.	CNPJ-OIB

(*) Campo obrigatório

6. Cadastrando reivindicações autoridade

Esta seção explica as etapas para cadastrar reivindicações de autoridade e como adicionar usuários com suas respectivas funções que serão desempenhadas pela organização dentro do Open Insurance.

Nome da modalidade no diretório	Descrição
DADOS	Instituição transmissora e/ou receptora de dados é a instituição que sendo: • Transmissora de dados: instituição participante que compartilha os dados com a instituição receptora; • Receptora de dados: instituição participante que apresenta solicitação de compartilhamento à instituição transmissora para recepção dos dados.

Nota: As modalidades assumidas pelos participantes no âmbito do Open Insurance são auto declaratórias e podem ser exercidas simultaneamente. Contudo, tais modalidades deverão estar em conformidade com o modelo de negócio do participante e estarão sujeitas à verificação pela fiscalização da SUSEP, especialmente com relação ao cumprimento do princípio da reciprocidade no compartilhamento de dados no Open Insurance Brasil.

ETAPA 1: Cadastrando uma nova reivindicação de função

Requisitos

Necessário realizar a seção "Cadastrando reivindicações de domínio de autoridade".
No Diretório, localize e selecione a sua organização.
Selecione o menu Authority Domain Role Claims e clique no botão New Role Claim.
Na janela New Authority Domain Role Claim preencha os campos do formulário. A seguir serão apresentados os campos em mais detalhes.
Clique no botão Save.

Nome do campo	Descrição	Exemplo
Authority Name*	Selecione o nome da autoridade.	Seguradora Semicredi
Authorisation Domain Name*	Selecione o nome de domínio de autorização.	Open Insurance Brasil
Role*	Selecione a modalidade (função).
Unique Technical Identifier	Selecione o identificador técnico único.
Registration ID*	Deve ser informado o número de registro único [ISPB-OBBFUNÇÃO]. Substitua o [ISPB] pelos primeiros 8 dígitos do seu CNPJ e o [FUNÇÃO] pela sigla da função que você está inserindo.	12345678-OBB-DADOS

(*) Campo obrigatório

ETAPA 2: Cadastrando um usuário de domínio de autorização

Requisitos

Necessário ter realizado o cadastro de uma nova reivindicação de domínio.
No Diretório, localize e selecione a sua organização.
Selecione o menu Authority Domain Role Claims. será carregado um submenu na parte superior esquerda. Então, clique no link Authorisation Domain User.
Na janela, clique no botão New Authorisation Domain User.
Na janela New Authorisation Domain User, preencha os campos do formulário.
Clique no botão Save.

Nome do campo	Descrição	Exemplo
Domain Name	É apresentado o domínio de autorização para o qual esta reivindicação de domínio está mapeada.	Open Insurance Brasil
Authorisation Domain Role	É apresentada a função mapeada para o domínio de autorização.	DADOS
System*	Selecione o sistema de contato: Directory, Service Desk, Dispute Resolution, Portal ou Centralized Platform. Para obter mais detalhes, verifique em "Sistemas e Funções de um usuário/contato".	Directory
Contact Role*	Selecione o papel assumido pelo contato. Para obter mais detalhes, verifique em "Sistemas e Funções de um usuário/contato".	PBC
E-mail*	Deve ser informado o endereço de e-mail corporativo do contato.	maria.gomes@semicredi.com.br

(*) Campo obrigatório

Sistemas e funções de um usuário/contato

Notas

Os perfis para os sistemas Directory, Service Desk e Dispute Resolution são obrigatórios.
Para obter mais detalhes dos poderes do usuário verifique a tabela "Modelo de Segurança".
Podem existir quantos contatos primários e secundários a instituição achar necessário.
Contatos primários podem acessar o Diretório e adicionar contatos secundários. Já os Contatos secundários não conseguem acessar o Diretório e, consequentemente, não conseguem adicionar novos usuários secundários.
A implementação dos poderes de acesso de contatos primários e secundários dependem e podem variar de plataforma.

7. Cadastrando servidores de autorização (authorisation servers)

Durante a jornada de consentimento do usuário, os receptores exibirão a marca e o servidor de autorização que está sendo solicitado o acesso aos dados do usuário. Esta seção descreve as etapas necessárias para cadastrar as marcas e os servidores de autorização da organização.

ETAPA 1: Criando um novo servidor de autorização

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Authorisation Servers. No canto superior esquerdo será carregado um submenu. Para cadastrar um novo Authorisation Server clique no botão New Authorisation Server localizado no lado direito da tela.
Na janela New Authorisation Server, preencha os campos do formulário. A seguir serão apresentados cada um dos campos em mais detalhes. Atenção 1: Tendo em vista a ausência de análise de impacto para o ecossistema da retirada de um Authorisation Server, recomenda-se que os(as) responsáveis por consentimentos não sejam retirados do diretório até a expiração/revogação dos consentimentos pelos quais é responsável. Atenção 2: Caso a instituição queira utilizar alguma chave forte, recomendamos utilizar o AuthorisationServerID. Os campos Customer Friendly Server Name e Description são especialmente suscetíveis a atualizações pelas organizações e não devem ser utilizados para esse fim.

Nome do campo	Descrição	Exemplo
Customer Friendly Server Name*	Deve ser definido o valor da marca que será exibido no receptor. Apresentar seu nome por inteiro, sem abreviações, de forma a ser reconhecido pelo cliente e aderente a interfaces menores. • Limite de caracteres: 40 (padrão do campo) Para mais informações sobre marca, consulte o Guia de Experiência de Usuário.	Semicredi
OpenID Discovery Document URI*	O URI para a localização do documento de descoberta OpenID.	https://www.semicredi.com.br/.well-known/openidconfiguration
Payload Signing Certificate URI*	O URI para a localização do certificado de assinatura.	https://www.semicredi.com.br/jwks

(*) Campo obrigatório

Nome do campo	Descrição	Exemplo
Customer Friendly Logo URI*	Deve ser definida a URI para o logotipo da marca. Para obter mais detalhes sobre formato, dimensão e peso máximo do arquivo consulte o Guia de Experiencia Fase 2.	https://wwww.semicredi.com.br/logo.svg
Developer Portal URI	O URI do portal do desenvolvedor.	https://developers.semicredi.com.br
Terms Of Service URI	A URI de localização do documento de termos e serviços da organização.	https://wwww.semicredi.com.br/tos.html
Notification Webhook Endpoint	Endpoint do Webhook de notificação. A seção Configurando Eventos de Notificação no Diretório descreve esta configuração em mais detalhes.	https://webhook.site/9d84a827-c200-4170-b0f8-f830170037bb
Description*	Esse é um texto de marcação onde deverá ser descrita a marca, trazendo informações adicionais para que o cidadão não tenha dúvidas sobre a escolha feita. 1. Limite de caracteres: 256 (padrão do campo). 2. Não deve ser permitido que a descrição traga links. 3. Orientações sobre o que pode conter: • Texto institucional de apresentação. • Desde quanto atua. • Diferenciais de atuação. • Canais de atendimento.	“A instituição Semicredi atua desde 1999 sendo uma das maiores seguradoras do Brasil, seja na web ou pelo App oferecemos produtos para sua família, empresa, carro e casa.”

Nota: O campo Customer Friendly Logo URI é o que a receptora deverá utilizar para apresentar a logomarca da transmissora.

(*) Campo obrigatório

Detalhamento do Logotipo

O logotipo das instituições participantes deverá ser aplicado no Portal do Cidadão e também poderá ser aplicado no redirecionamento entre instituições durante a Jornada de Compartilhamento de Dados. Por isso foram deliberadas práticas para uso e disponibilização:
• Utilizar preferencialmente logotipo prioritário, que os clientes reconheçam nos canais.
• Versão reduzida do logo, símbolo ou favicon de site.
• Enviar arquivo SVG contendo a área de proteção do logo da instituição para garantir a leitura e o espaçamento correto.
• Formato de envio:
_{SVG
Dimensão mínima: 512px x 512px
Sem sombra}
• Peso máximo do arquivo: 1 mega.

ETAPA 2: Cadastrando certificação de segurança no servidor

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Authorisation Servers. Depois selecione o servidor de autorização que deseja. Após selecionar, vá no submenu do lado superior esquerdo e clique em Server Certifications.
Dentro dessa área, para cadastrar uma nova certificação, clique no botão Add New Certification localizado no lado direito da tela.
Na janela New certification preencha os campos do formulário. A seguir serão apresentados os campos em mais detalhes.

As informações da certificação do Authorisation Server são referentes à certificação FAPI obtida através da OpenID Foundation. Dentro do site é possível encontrar uma tabela Open Insurance Brazil (Based on FAPI 1 Advanced Final) que contém as informações que devem ser refletidas no formulário para adição da certificação de segurança.

Nome do campo	Descrição	Exemplo
Certification type*	O tipo de certificação que foi efetuada com a OpenID Foundation – Deve ser adicionado ao menos uma certificação Redirect (FAPI) e uma DCR.	Redirect DCR CIBA – certificação ainda não disponível
Certification type variant*	As variantes dependem do tipo de certificação escolhida.	Dentro da tabela da OpenID Foundation, cada coluna representa as possíveis variações nas certificações. Para a certificação DCR, a instituição deve avaliar se certificou utilizando APIs de Dados do consumidor – Unsigned, ou de Pagamentos - Signed.
Profile version*	A versão da certificação selecionado – Campo livre, apenas para controle da própria instituição.	1
Certification payload*	O URI que aponta para o arquivo hospedado pela OpenID Foundation com o pacote de certificação. Formato zip.	https://openid.net/wordpresscontent/uploads/2021/08/BR-OB_Adv._OP_MTLSexemplo.zip
Start date of certification*	A data de certificação inicial – é a mesma data que consta na tabela da OpenID Foundation. Formato dd/mm/yyyy	09/05/2022

(*) Campo obrigatório

8. Cadastrando recursos de uma API (endpoints)

Esta seção explica as etapas para cadastrar os endpoints de recursos de uma API.

Cadastramento de Recursos

Para cada uma das famílias de APIs devem ser adicionados todos os endpoints disponíveis. Segue abaixo um exemplo de disponibilização do cadastramento de recursos:

Nota: Na Fase 2 o padrão de cadastramento continua como na Fase 1. Seguem, aqui, alguns pontos de atenção:
• Na API de consentimento é necessário apenas o cadastramento de uma entrada para o GET e o DELETE;
• A API de customers foi dividida em duas famílias para facilitar o consumos pelos receptores. Customers-business onde é cadastrado os Endpoints PJ e customers-personal onde será cadastrado os endpoints PF. Cabendo aqui o cadastramento conforme a disponibilização do produto pela instituição;

Tabela Exemplo Recursos Fase 1

API	Diretório (Family Type)	Recursos (resources)
discovery	discovery	https://api.organizacao.com.br/open-insurance/discovery/v1/status https://api.organizacao.com.br/open-insurance/discovery/v1/outages
data_channels	data_channels	https://api.organizacao.com.br/open-insurance/data_channels/v1/electronic-channels https://api.organizacao.com.br/open-insurance/data_channels/v1/branches https://api.organizacao.com.br/open-insurance/data_channels/v1/phone-channels
admin_metrics	admin_metrics	https://api.organizacao.com.br/open-insurance/admin_metrics/v1/admin_metrics

Observação: a tabela acima não é exaustiva, ou seja, não contém todas as APIs da Fase 1 para o Open Insurance Brasil.

Tabela Exemplo Recursos Fase 2

API	Diretório (Family Type)	Recursos (resources)
resources	resources	https://api.organizacao.com.br/open-insurance/resources/v1/
customers	customers	https://api.organizacao.com.br/open-insurance/customers/v1/personal/identifications https://api.organizacao.com.br/open-insurance/customers/v1/business/identifications

Observação: a tabela acima não é exaustiva, ou seja, não contém todas as APIs da Fase 2 para o Open Insurance Brasil.

ETAPA 1: Cadastrando um novo recurso de uma API

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Authorisation Servers e clique no link do servidor de autorização na qual se deseja cadastrar os recursos.
No canto superior esquerdo da página clique em API Resources.
Na página que será carregada, clique no botão New API Resources para abrir a janela New API Resource.
Na janela New API Resource, clique na caixa de seleção API Family Type e selecione uma das opções disponíveis.
No campo ao lado, em Version especifique o valor apropriado utilizando versionamento semântico (major.minor.patch, exemplo: 1.0.7)
No campo Certification URI é necessário informar a URI onde se encontra a localização do certificado publicado no GitHub. Este preenchimento é obrigatório para famílias de APIs a partir da Fase 2.
Clique no botão Save.

Nota: No ambiente de Sandbox do Diretório, caso não exista uma certificação, é possível incluir um endereço para testes: https://openinsurance-brasil.github.io/teste.zip
De volta à tela API Resources, informe URI principal no campo API Discovery Endpoints e, em seguida, pressione a tecla Enter.
Para cada uma das famílias de APIs repita os passos 4 a 8.

Nota: Todos os endpoints deverão ser preenchidos, incluindo os respectivos recursos. Para obter mais detalhes sobre o padrão do endpoints e versão consulte o Portal do Desenvolvedor do Open Insurance

9. Cadastrando declarações de software (software statements)

Aqui apresentamos a configuração necessária para criar uma nova declaração de software no Diretório.

ETAPA 1: Criando uma nova declaração de software

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Software Statements e clique no botão New Software Statement.
Na janela New Software Statement preencha os campos do formulário. A seguir serão apresentados cada um dos campos em mais detalhes.

Nome do campo	Descrição	Exemplo
Version*	A versão do software deve ser definida para um valor numérico, um número inteiro (por exemplo, 1) ou um número de ponto flutuante (1,2; 2,2; 3,2 , etc.)	1
Client Name*	Para registro de software da instituição receptora (software statement), no campo Client Name, recomenda-se usar o nome da Marca de conhecimento do cliente. Se o nome da marca foi declarado no Authorisation Server, por exemplo, pode-se usar o nome da marca que foi utilizado no cadastro (customer friendly server name). Este é o nome que a transmissora irá receber e declarar ao cliente durante a jornada.	Seguradora Semicredi
Client URI*	O site ou URI raiz do recurso, podendo ser o site institucional da organização.	https://www.semicredi.com.br/info.html.
Policy URI	Deve ser definido como uma sequência de texto que representa uma URI única de política.	https://www.semicredi.com.br/policy.html
Logo URI*	Deve ser definida a URI para o logotipo da marca. Para obter mais detalhes sobre formato, dimensão e peso máximo do arquivo consulte o Guia de Experiencia Fase 2	https://www.semicredi.com.br/logo.svg
Redirect URI*	Os URIs de redirecionamento devem ser definidos como uma string de texto que representa uma URI única de redirecionamento.	https://www.semicredi.com.br/cb1 https://www.semicredi.com.br/cb2
Terms of Service	URI	Deve ser definido como uma string de texto que representa uma URI única dos Termos de Serviço. https://www.semicredi.com.br/tos.html
Description	Deve ser definido como uma string de texto de sua escolha.	Aplicativo Seguradora Semicredi para o segmento de varejo.
On Behalf Of	O campo “Em nome de” é classificado como opcional para implementação.	Não se aplica para o contexto do Open Insurance Brasil

Nota: O campo Logo URI é o que a transmissora deverá utilizar para apresentar a logomarca da receptora.

(*) Campo obrigatório.

ETAPA 2: Cadastrando certificação de declaração de software

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Software Statements. Em seguida, selecione a declaração de software que deseja. Após selecionar, vá no submenu à esquerda em cima e clique em Certifications.
Dentro dessa área, para cadastrar uma nova certificação, clique no botão Add New Certification localizado no lado direito da tela.
Na janela New certification preencha os campos do formulário. A seguir serão apresentados cada um dos campos em mais detalhes.
As informações da certificação do Software Statement são referentes a certificação FAPI obtida através da OpenID Foundation . Dentro do site é possível encontrar a tabela Brasil Open Insurance (Based on FAPI Relying Parties) que contém as informações que devem ser refletidas no formulário para adição da certificação de segurança.

Nome do campo	Descrição	Exemplo
Certification type*	O tipo de certificação que foi efetuada com a OpenID Foundation – Deve ser adicionada, ao menos, uma certificação Redirect (FAPI e DCR).	Redirect DCR CIBA – certificação ainda não disponível
Certification type variant*	As variantes dependem do tipo de certificação escolhida. Dentro da tabela da OpenID Foundation cada coluna representa as possíveis variações nas certificações. Vale notar que JARM não é requisitado segundo a especificação de segurança, portanto não está presente como uma opção a ser adicionada. Para a certificação DCR a instituição deve avaliar se certificou utilizando APIs de Dados do consumidor – Unsigned, ou de Pagamentos - Signed.	Se escolheu Redirect: • FAPI Adv. OP w/ MTLS • FAPI Adv. OP w/ MTLS, PAR • FAPI Adv. OP w/ Private Key • FAPI Adv. OP w/ Private Key, PAR Se escolheu DCR: • DCR Signed payload – JWT • DCR Unsigned payload - JSON
Profile version*	A versão da certificação selecionado – Campo livre, apenas para controle da própria instituição.	1
Certification payload*	O URI que aponta para o arquivo hospedado pela OpenID Foundation com o pacote de certificação. Formato zip.	https://openid.net/wordpresscontent/uploads/2021/08/BR-OB_Adv._OP_MTLSexemplo.zip
Start date of certification*	A data de certificação inicial – é a mesma data que consta na tabela da OpenID Foundation. Formato dd/mm/yyyy	09/05/2022

(*) Campo obrigatório

10. Criando uma nova reivindicação de autoridade de software

Esta seção explica as etapas para criar uma reivindicação de autoridade de software. Esta etapa será necessária para definir as funções regulatórias que serão inseridas no Software Statement Assertion.

ETAPA 1: Criando reivindicação de autoridade de software

Requisitos

Necessário realizar a seção "Cadastrando reivindicações de domínio de autoridade".
Necessário realizar a seção "Cadastrando reivindicações de autoridade".
Necessário ter criado um Software Statements para sua organização.
No Diretório, selecione a sua organização e, no menu lateral, clique em Software Statements.
No menu lateral, selecione a opção Authority Claims. Na janela Software Statements Details, role a página para baixo, selecione o menu Authority Claims e clique no botão New Software Authority Claims.
Na janela New Software Authority Claims preencha os campos do formulário. Os campos serão apresentados, a seguir, em mais detalhes.

Nome do campo	Descrição	Exemplo
Authorisation Domain Name	É apresentado o domínio de autorização para o qual esta a reivindicação de domínio está mapeada.	Open Insurance Brasil
Role	É apresentada a função mapeada para o domínio de autorização.	DADOS

(*) Campo obrigatório

11. Criando certificados de transporte e assinatura em Sandbox

As etapas para criar uma Solicitação de Assinatura de Certificado para certificados de transporte e assinatura que não foram emitidos por uma autoridade de certificação e para uso exclusivo em ambiente de Sandbox do Diretório, podem ser acessadas através dos links:

http://hml-dev-portal.s3-website.us-east-2.amazonaws.com/files/OpenInsurance_Gerando_o_Certificado_BRCAC.pdf

http://hml-dev-portal.s3-website.us-east-2.amazonaws.com/files/OpenInsurance_Gerando_o_Certificado_BRSEAL.pdf

12. Carregando certificados emitidos por autoridade de certificação em Produção

Esta seção explica as etapas para importar certificados que foram emitidos por uma autoridade de certificação e para uso exclusivo em ambiente de Produção do Diretório.

ETAPA 1: Carregando certificado de transporte

Requisitos

Necessário ter criado um Software Statements para sua organização.
No Diretório, selecione a sua organização e, em seguida, selecione o menu Software Statements.
Na tela Software Statement, clique no botão New Certificate.
Na janela New Certificate, na caixa de seleção Select Certificate Type, selecione a opção EXTERNAL BRCAC e clique no botão Continue.
No passo seguinte, em "Generate CSR", clique no botão Continue.
Na opção "Upload CSR/PEM", localize o arquivo.csr e clique no botão Continue.
Aguarde o carregamento do arquivo para o Diretório e, em seguida, clique no botão Done.
Na tela anterior de certificates, vá até actions e clique na seta de download. Salve o arquivo.pem em uma pasta local.

ETAPA 2: Carregando certificado de assinatura

Requisitos

No Diretório, selecione a sua organização e clique em Organisations Certificate no menu lateral.
Na janela New Organisations Certificate, na caixa de seleção Select Certificate Type, selecione a opção BRSEAL EXTERNAL e clique no botão Continue.
No passo seguinte, em Generate CSR, clique no botão Continue.
Na opção Upload CSR/PEM, localize o arquivo.csr e clique no botão Continue.
Aguarde o carregamento do arquivo para o Diretório e no passo seguinte clique no botão Done.
Na tela anterior em Organisation Certificates, vá até actions e clique na seta de download. Salve o arquivo.pem em uma pasta local.

13. Cadastrando administradores da organização

Esta seção explica as etapas necessárias para realizar o cadastro de um novo administrador da organização.

ETAPA 1: Cadastrando um administrador da organização

Requisitos

No Diretório, localize e selecione a sua organização.
Selecione o menu Organisation Administrator e clique no botão New Organisation Administrators.
Na janela New Organisation Administrator preencha o campo do formulário.
Clique no botão Save.

Nota: somente administradores da organização podem cadastrar novos administradores.

14. Obtendo um Software Statements Assertion

Uma Software Statements Assertion (SSA) é um JWT assinado do diretório que contém todas as informações sobre um aplicativo que existe em um determinado momento no diretório. Inclui a localização de todas as chaves públicas vinculadas a esta declaração de software e todos os outros metadados de que um banco precisa para validar a legitimidade do aplicativo.

ETAPA 1: Criando uma nova declaração de software assinada

Requisitos

Necessário ter criado um Software Statements para sua organização.
No Diretório, localize e selecione a sua organização.
Vá até o menu Software Statement, acesse o artefato criado anteriormente clicando no link CLIENT NAME.
Na janela Software Statement Details, role a página para baixo e selecione o menu Software Statements Assertion.
Clique no botão Copy to Clipboard para copiar o SSA gerado pelo Diretório.

15. Configurando eventos de notificação no Diretório

Aqui apresentamos a configuração de Webhook no Diretório.

ETAPA 1: Inscrever-se em um tópico

Requisitos

Em seu navegador, navegue até webhook.site e uma URL única e aleatória será gerada automaticamente. Ela poderá ser utilizada para testar e depurar Webhooks e solicitações HTTP.
Selecione a URL e a copie.

ETAPA 2: Solicitando uma subscrição

Requisitos

No Diretório, selecione a sua organização e vá até a página "detalhes da organização".
Selecione o menu Authorisation Servers e, em actions, clique no ícone de edição.
Na página Authorisation Server Information, cole a URL obtida na Etapa 1 no campo Notification Webhook Endpoint.

ETAPA 3: Confirmando uma subscrição

Requisitos

De volta ao webhook.site, role para baixo e no campo de texto Raw Context selecione e copie a URL em SubscribeURL para se subscrever no tópico.
Em uma nova aba do navegador, cole a URL obtida no passo anterior.
Pronto! A partir daqui, toda e qualquer modificação que ocorra no Diretório será notificada através de eventos.

ETAPA 4: Analisando um evento de notificação

Requisitos

No Diretório, selecione a sua organização e vá até a página detalhes da organização.
Selecione o menu Software Statement e em actions clique no ícone editar.
Na janela Software Statement Details vá até o campo description e digite qualquer valor e clique no botão Salvar.
Neste momento, o Diretório irá enviar uma notificação push.
De volta ao webhook.site, clique no primeiro evento que surge na lista a esquerda da tela.
Role a tela para baixo e no campo de texto Raw Context localize o novo valor adicionado no atributo description.

16. Obtendo um token de acesso para as APIs do Diretório

Para acessar as APIs do Diretório do Open Insurance, você precisará de um token de acesso. Esta seção descreve as etapas necessárias para adquirir tokens de acesso.

ETAPA 1: Localizando o identificador do cliente

Requisitos

Necessário ter criado um Software Statements para sua organização.
No Diretório, localize e selecione a sua organização.
Vá até o menu Software Statement, acesse o artefato criado anteriormente clicando no símbolo do lápis.
Na janela Software Statement Details localize o campo CLIENT ID, selecione e copie o valor.

ETAPA 2: Localizando a URI de token no Diretório

Requisitos

No navegador, acesse a URI de descoberta de conexão OpenID de acordo com o ambiente utilizado:

Sandbox

https://auth.sandbox.directory.opinbrasil.com.br/.well-known/openid-configuration

Produção

https://auth.directory.opinbrasil.com.br/.well-known/openid-configuration

Localize o endpoint de token que será utilizado para trocar as credenciais de autenticação para tokens de acesso.

ETAPA 3: Adicionando certificados SSL por domínio

Requisitos

Necessário ter criado uma Solicitação de Assinatura de Certificado (CSR).
Será utilizado o Postman, com fins ilustrativos, para acessar as APIs do Diretório do Open Insurance Brasil. Assim, no Postman, selecione o menu File e em seguida o menu Settings. Um atalho para acessar esta janela é o comando: Ctrl + Vírgula.
Na janela Settings, selecione o menu Certificates e clique no link Add Certificate.
Na aba Certificates, no campo Host insira um dos valores descritos a seguir de acordo com o ambiente utilizado:

Sandbox

matls-auth.sandbox.directory.opinbrasil.com.br

e

matls-api.sandbox.directory.opinbrasil.com.br

Produção

Matls-auth.directory.opinbrasil.com.br

e

Matls-api.directory.opinbrasil.com.br
Em CRT file, clique no botão Select file, e localize o arquivo.pem obtido na seção Criando uma solicitação de Assinatura de Certificado (CSR).
No passo seguinte, clique no botão KEY File e localize o arquivo.Key criado no processo de geração de chaves na seção "Criando uma solicitação de Assinatura de Certificado (CSR)".
Clique no botão Add.

ETAPA 4: Obtendo um token de acesso

Requisitos

Para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, digite o valor obtido da URI de token mencionado na etapa 2.
Defina o tipo da operação para POST.
Vá para a guia Body e selecione o botão de opção‘x-www-form-urlencoded’.
Insira os parâmetros como descritos a seguir:

client_id =

grant_type = client_credentials

scope = directory:software
Uma vez que todos os parâmetros e valores estejam preenchidos, clique no botão Send.
Selecione e copie o valor retornado no atributo access_token.

17. Listando as organizações cadastradas no Diretório via API

Você precisará de um token de acesso para acessar a API Organisations no Diretório. Esta seção descreve as etapas necessárias para listar e visualizar os detalhes das organizações cadastradas no Diretório.

ETAPA 1: Obtendo detalhes das organizações

Requisitos

Necessário ter um token de acesso. Veja mais detalhes em "Obtendo um token de acesso para acessar as APIs do Diretório".
Para fins ilustrativos será utilizado o Postman para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:

Sandbox

https://matls-api.sandbox.directory.opinbrasil.com.br/organisations

Produção

https://matls-api.directory.opinbrasil.com.br/organisations
Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token cole o access_token obtido na seção "Obtendo um token de acesso para acessar as APIs do Diretório".
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.

Nota: Para localizar uma organização mãe que pertença a um conglomerado, você poderá percorrer na lista de resposta de dados JSON do servidor, capturando o identificador no atributo ParentOrganisationReference das organizações filhas e localizar o mesmo ID na organização cujo o atributo RegistrationId contenha este mesmo valor.

18. Listando os servidores de autorização de uma organização via API

Aqui apresentamos os passos para listar os servidores de autorização de uma organização.

ETAPA 1: Listando os servidores de autorização

Requisitos

Necessário ter um token de acesso. Veja mais detalhes em "Obtendo um Token de Acesso para acessar as APIs do Diretório".
Necessário ter realizado os passos da seção "Listando as organizações cadastradas no Diretório via API".
Será utilizado o Postman, com fins ilustrativos, para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:

Sandbox

matls-api.sandbox.directory.opinbrasil.com.br/organisations//authorisationservers

Produção

matls-api.directory.opinbrasil.com.br/organisations//authorisationservers
Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token, cole o access_token obtido na seção Obtendo um Token de Acesso para acessar as APIs do Diretório.
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.

Nota: Na resposta de dados JSON do servidor o atributo customerFriendlyName contém o valor da marca e o CustomerFriendlyLogoUri o logotipo vinculado à marca.

19. Obtendo um Software Statement via API

Aqui apresentamos os passos para obter um Software Statement (SS) no Diretório via API.

ETAPA 1: Obtendo um SS no Diretório via API

Requisitos

Necessário ter um token de acesso. Veja mais detalhes em Obtendo um token de acesso para acessar as APIs do Diretório.
Necessário ter realizado os passos da seção "Listando as Organizações Cadastradas no Diretório via API".
Para fins ilustrativos será utilizado o Postman para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:

Sandbox

matls-api.sandbox.directory.opinbrasil.com.br/organisations//softwarestatements

Produção

matls-api.directory.opinbrasil.com.br/organisations//softwarestatement
Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token cole o access_token obtido na seção "Obtendo um Token de Acesso para acessar as APIs do Diretório".
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.

20. Obtendo um Software Statement Assertion via API

Aqui apresentamos os passos para obter um Software Statement Assertion (SSA) no Diretório via API.

ETAPA 1: Obtendo um SSA do Diretório via API

Requisitos

Necessário ter um token de acesso. Veja mais detalhes em "Obtendo um Token de Acesso para acessar as APIs do Diretório".
Necessário ter realizado os passos da seção "Listando as organizações cadastradas no Diretório via API".
Necessário ter realizado os passos da seção "Obtendo um Software Statement via API".
Será utilizado o Postman, com fins ilustrativos, para acessar as APIs do Diretório do Open Insurance Brasil. Assim, para adicionar uma nova requisição a uma coleção, vá no canto superior esquerdo em Collection, clique em ‘...’ na coleção e escolha Add Request. Você também pode criar uma solicitação clicando no menu File > New, e em seguida Request.
No campo Enter request URL, insira um dos valores descritos a seguir de acordo com o ambiente utilizado:

Sandbox

matls-api.sandbox.directory.opinbrasil.com.br/organisations//softwarestatements//assertion

Produção

matls-api.directory.opinbrasil.com.br/organisations//softwarestatements//assertion
Defina o tipo da operação para GET.
Vá para a guia Authorisation e na caixa de seleção Type selecione a opção Bearer Token.
Na coluna ao lado, no campo Token, cole o access_token obtido na seção "Obtendo um Token de Acesso para acessar as APIs do Diretório".
Uma vez que todos os valores estejam preenchidos, clique no botão Send. Você verá a resposta de dados JSON do servidor no painel inferior.

21. Como se inscrever nas atualizações de lançamento do Diretório

Constantemente são realizados aprimoramentos e atualizações no Diretório. Estas mudanças são registradas em uma página Web onde reside todo o conteúdo do Release Notes. Esta seção descreve as etapas necessárias de inscrição para o recebimento de notificação do release notes do Diretório quando publicado.

ETAPA 1: Cadastrando o recebimento de release notes.

Requisitos

Em seu navegador, navegue até site de monitoramento de disponibilidade do Diretório.
Clique em “Subscrever atualizações”.
Na tela seguinte, adicione seu e-mail e clique no botão "Subscrever". O Diretório irá enviar uma mensagem de confirmação, que será encaminhada ao endereço de e-mail informado.
No e-mail recebido, clique no botão "Sim, subscreve-me".
Em uma página da Web será apresentada a mensagem informando que seu e-mail encontra-se, agora, subscrito para atualizações de estado Open Insurance Brasil.

Nota: Caso você não tenha recebido o e-mail de confirmação, verifique sua caixa de SPAM e as políticas de bloqueio de mensagens. O envio das mensagens poderá sofrer algum atraso. Contudo, se o problema persistir, clique no botão "Subscrever Alterações" para reenvio das mensagens.

ETAPA 2: Acessando o Release Notes

Requisitos

No navegador, digite a URL de acordo com o ambiente a ser acessado:

Sandbox

https://data.sandbox.directory.opinbrasil.com.br/release-notes

Produção

https://data.directory.opinbrasil.com.br/release-notes

22. Como obter suporte ao Diretório

Aqui apresentamos as formas de contato para suporte ao Diretório Central.

SERVICE DESK

Todas as consultas, problemas ou solicitações de suporte precisam ser roteados por meio do Service Desk.

O Service Desk do Open Insurance Brasil pode ser acessado pelo endereço: https://servicedesk.opinbrasil.com.br/

É possível abrir chamados de Solicitação de Informações, Melhorias, Incidentes de Indisponibilidade e Problemas de Performance.

Schemas

BadRequest

{
  "errors": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
errors	[string]	false	none	Validation Error messages

PageableRequest

{
  "page": 0,
  "size": 2,
  "sort": "status,desc"
}

Properties

Name	Type	Required	Restrictions	Description
page	integer	false	none	Page index starts from 0
size	integer	false	none	This sets the page size
sort	string	false	none	Used to sort based on Model Parameters

UserUpdateRequest

{
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
Status	StatusEnum	false	none	none

StatusEnum

"Active"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	Active
anonymous	Inactive

OrganisationAuthorityClaims

[
  {
    "OrganisationId": "string",
    "OrganisationAuthorityClaimId": "string",
    "AuthorityId": "string",
    "Status": "Active",
    "AuthorisationDomain": "string",
    "Role": "string",
    "Authorisations": [
      {
        "Status": "Active",
        "MemberState": "st"
      }
    ],
    "RegistrationId": "string",
    "UniqueTechnicalIdenifier": [
      "string"
    ]
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[OrganisationAuthorityClaim]	false	none	none

OrganisationAuthorityClaim

{
  "OrganisationId": "string",
  "OrganisationAuthorityClaimId": "string",
  "AuthorityId": "string",
  "Status": "Active",
  "AuthorisationDomain": "string",
  "Role": "string",
  "Authorisations": [
    {
      "Status": "Active",
      "MemberState": "st"
    }
  ],
  "RegistrationId": "string",
  "UniqueTechnicalIdenifier": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
OrganisationAuthorityClaimId	OrganisationAuthorityClaimId	false	none	Unique ID associated with the authority claims
AuthorityId	AuthorityId	false	none	Unique ID associated with the Authorisation reference schema
Status	string	false	none	Is this software statement Active/Inactive
AuthorisationDomain	string	false	none	Authorisation Domain for the authority
Role	string	false	none	Roles for the Authority i.e. ASPSP, AISP, PISP, CBPII
Authorisations	[object]	false	none	none
» Status	string	false	none	Is this authorsation Active/Inactive
» MemberState	string	false	none	Abbreviated states information i.e. GB, IE, NL etc
RegistrationId	string	false	none	Registration ID for the organisation
UniqueTechnicalIdenifier	[string]	false	none	none

Enumerated Values

Property	Value
Status	Active
Status	Inactive
Status	Active
Status	Inactive

OrganisationAuthorityClaimRequest

{
  "AuthorityId": "string",
  "Status": "Active",
  "AuthorisationDomain": "string",
  "Role": "string",
  "RegistrationId": "string",
  "UniqueTechnicalIdenifier": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
AuthorityId	AuthorityId	true	none	Unique ID associated with the Authorisation reference schema
Status	string	true	none	Is this authority claim Active/Inactive, default is Active
AuthorisationDomain	string	true	none	Authorisation domain for the authority
Role	string	true	none	Role for the authority
RegistrationId	string	true	none	Registration ID for the organisation
UniqueTechnicalIdenifier	[string]	false	none	none

Enumerated Values

Property	Value
Status	Active
Status	Inactive

OrganisationAuthorityClaimAuthorisations

[
  {
    "OrganisationAuthorisationId": "string",
    "OrganisationAuthorityClaimId": "string",
    "Status": "Active",
    "MemberState": "string"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[OrganisationAuthorityClaimAuthorisation]	false	none	none

OrganisationAuthorityClaimAuthorisation

{
  "OrganisationAuthorisationId": "string",
  "OrganisationAuthorityClaimId": "string",
  "Status": "Active",
  "MemberState": "string"
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationAuthorisationId	OrganisationAuthorisationId	false	none	Unique ID associated with authorisations for organisation's authority claims
OrganisationAuthorityClaimId	OrganisationAuthorityClaimId	false	none	Unique ID associated with the authority claims
Status	string	false	none	Is this authority claim Active/Inactive
MemberState	string	false	none	Abbreviated states information i.e. GB, IE, NL etc

Enumerated Values

Property	Value
Status	Active
Status	Inactive

OrganisationAuthorityClaimAuthorisationRequest

{
  "Status": "Active",
  "MemberState": "string"
}

Properties

Name	Type	Required	Restrictions	Description
Status	string	true	none	Is this Active/Inactive - default is Active
MemberState	string	true	none	Abbreviated states information i.e. GB, IE, NL etc

Enumerated Values

Property	Value
Status	Active
Status	Inactive

AuthorisationServers

[
  {
    "AuthorisationServerId": "string",
    "OrganisationId": "string",
    "AutoRegistrationSupported": true,
    "ApiResources": [
      {
        "ApiResourceId": "string",
        "ApiFamilyType": "string",
        "ApiVersion": 0,
        "ApiDiscoveryEndpoints": [
          {
            "ApiDiscoveryId": "string",
            "ApiEndpoint": "http://example.com"
          }
        ]
      }
    ],
    "CustomerFriendlyDescription": "string",
    "CustomerFriendlyLogoUri": "http://example.com",
    "CustomerFriendlyName": "string",
    "DeveloperPortalUri": "http://example.com",
    "TermsOfServiceUri": "http://example.com",
    "NotificationWebhook": "http://example.com",
    "NotificationWebhookStatus": "string",
    "OpenIDDiscoveryDocument": "http://example.com",
    "PayloadSigningCertLocationUri": "http://example.com",
    "ParentAuthorisationServerId": "string"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[AuthorisationServer]	false	none	none

AuthorisationServer

{
  "AuthorisationServerId": "string",
  "OrganisationId": "string",
  "AutoRegistrationSupported": true,
  "ApiResources": [
    {
      "ApiResourceId": "string",
      "ApiFamilyType": "string",
      "ApiVersion": 0,
      "ApiDiscoveryEndpoints": [
        {
          "ApiDiscoveryId": "string",
          "ApiEndpoint": "http://example.com"
        }
      ]
    }
  ],
  "CustomerFriendlyDescription": "string",
  "CustomerFriendlyLogoUri": "http://example.com",
  "CustomerFriendlyName": "string",
  "DeveloperPortalUri": "http://example.com",
  "TermsOfServiceUri": "http://example.com",
  "NotificationWebhook": "http://example.com",
  "NotificationWebhookStatus": "string",
  "OpenIDDiscoveryDocument": "http://example.com",
  "PayloadSigningCertLocationUri": "http://example.com",
  "ParentAuthorisationServerId": "string"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationServerId	AuthorisationServerId	false	none	none
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
AutoRegistrationSupported	boolean	false	none	none
ApiResources	[ApiResource]	false	none	none
CustomerFriendlyDescription	string	false	none	none
CustomerFriendlyLogoUri	string(uri)	false	none	A compliant URI
CustomerFriendlyName	string	false	none	none
DeveloperPortalUri	string(uri)	false	none	A compliant URI
TermsOfServiceUri	string(uri)	false	none	A compliant URI
NotificationWebhook	string(uri)	false	none	A compliant URI
NotificationWebhookStatus	string	false	none	If the webhook has confirmed subscription
OpenIDDiscoveryDocument	string(uri)	false	none	A compliant URI
PayloadSigningCertLocationUri	string(uri)	false	none	A compliant URI
ParentAuthorisationServerId	AuthorisationServerId	false	none	none

AuthorisationServerRequest

{
  "AutoRegistrationSupported": true,
  "CustomerFriendlyDescription": "string",
  "CustomerFriendlyLogoUri": "string",
  "CustomerFriendlyName": "string",
  "DeveloperPortalUri": "string",
  "TermsOfServiceUri": "string",
  "NotificationWebhook": "string",
  "OpenIDDiscoveryDocument": "string",
  "PayloadSigningCertLocationUri": "string",
  "ParentAuthorisationServerId": "string"
}

Properties

Name	Type	Required	Restrictions	Description
AutoRegistrationSupported	boolean	true	none	Default is true
CustomerFriendlyDescription	string	false	none	A customer friendly description
CustomerFriendlyLogoUri	string	true	none	A compliant URI
CustomerFriendlyName	string	true	none	none
DeveloperPortalUri	string	true	none	A compliant URI
TermsOfServiceUri	string	true	none	A compliant URI
NotificationWebhook	string	false	none	A compliant URI
OpenIDDiscoveryDocument	string	true	none	A compliant URI
PayloadSigningCertLocationUri	string	true	none	A compliant URI
ParentAuthorisationServerId	AuthorisationServerId	false	none	none

AuthorisationServerId

"string"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

CertificateOrKeyOrJWT

"string"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

CertificateOrKeyId

"string"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

CertificatesOrKeys

[
  {
    "OrganisationId": "string",
    "SoftwareStatementIds": [
      "string"
    ],
    "ClientName": "string",
    "Status": "string",
    "ValidFromDateTime": "string",
    "ExpiryDateTime": "string",
    "e": "string",
    "keyType": "string",
    "kid": "string",
    "kty": "string",
    "n": "string",
    "use": "string",
    "x5c": [
      "string"
    ],
    "x5t": "string",
    "x5thashS256": "string",
    "x5u": "string",
    "SignedCertPath": "string",
    "JwkPath": "string",
    "OrgJwkPath": "string"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[CertificateOrKey]	false	none	none

CertificateOrKey

{
  "OrganisationId": "string",
  "SoftwareStatementIds": [
    "string"
  ],
  "ClientName": "string",
  "Status": "string",
  "ValidFromDateTime": "string",
  "ExpiryDateTime": "string",
  "e": "string",
  "keyType": "string",
  "kid": "string",
  "kty": "string",
  "n": "string",
  "use": "string",
  "x5c": [
    "string"
  ],
  "x5t": "string",
  "x5thashS256": "string",
  "x5u": "string",
  "SignedCertPath": "string",
  "JwkPath": "string",
  "OrgJwkPath": "string"
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
SoftwareStatementIds	[SoftwareStatementId]	false	none	[Unique Software Statement Id]
ClientName	string	false	none	none
Status	string	false	none	none
ValidFromDateTime	string	false	none	none
ExpiryDateTime	string	false	none	none
e	string	false	none	none
keyType	string	false	none	none
kid	string	false	none	none
kty	string	false	none	none
n	string	false	none	none
use	string	false	none	none
x5c	[string]	false	none	none
x5t	string	false	none	none
x5thashS256	string	false	none	none
x5u	string	false	none	none
SignedCertPath	string	false	none	Used to display location of the signed certificate in PEM format
JwkPath	string	false	none	Used to display path to JWKS containing this certificate
OrgJwkPath	string	false	none	Used to display path to Org JWKS containing org certificates

AmendCertificateRequest

{
  "RevokeReason": "unspecified"
}

Properties

Name	Type	Required	Restrictions	Description
RevokeReason	string	true	none	Specify a reason for revokation of the certificate.

Enumerated Values

Property	Value
RevokeReason	unspecified
RevokeReason	keycompromise
RevokeReason	superseded
RevokeReason	cessationofoperation
RevokeReason	privilegewithdrawn

ContactRequest

{
  "ContactType": "Business",
  "FirstName": "string",
  "LastName": "string",
  "Department": "string",
  "EmailAddress": "string",
  "PhoneNumber": "stringst",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "City": "string",
  "Postcode": "string",
  "Country": "string",
  "AdditionalInformation": "string",
  "PgpPublicKey": "string"
}

Properties

Name	Type	Required	Restrictions	Description
ContactType	string	true	none	The type of Contact, default contact type is Business.
FirstName	string	false	none	none
LastName	string	false	none	none
Department	string	false	none	none
EmailAddress	string	true	none	none
PhoneNumber	string	true	none	none
AddressLine1	string	false	none	Address line 1
AddressLine2	string	false	none	Address line 2
City	string	false	none	City
Postcode	string	false	none	Postcode
Country	string	false	none	Country
AdditionalInformation	string	false	none	Any additional user information
PgpPublicKey	string	false	none	A PGP Public Key in text form

Enumerated Values

Property	Value
ContactType	Business
ContactType	Technical
ContactType	Billing
ContactType	Incident
ContactType	Security

Contacts

[
  {
    "ContactId": "string",
    "OrganisationId": "string",
    "ContactType": "Business",
    "FirstName": "string",
    "LastName": "string",
    "Department": "string",
    "EmailAddress": "string",
    "PhoneNumber": "string",
    "AddressLine1": "string",
    "AddressLine2": "string",
    "City": "string",
    "Postcode": "string",
    "Country": "string",
    "AdditionalInformation": "string",
    "PgpPublicKey": "string"
  }
]

The list of contacts

Properties

Name	Type	Required	Restrictions	Description
anonymous	[Contact]	false	none	The list of contacts

Contact

{
  "ContactId": "string",
  "OrganisationId": "string",
  "ContactType": "Business",
  "FirstName": "string",
  "LastName": "string",
  "Department": "string",
  "EmailAddress": "string",
  "PhoneNumber": "string",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "City": "string",
  "Postcode": "string",
  "Country": "string",
  "AdditionalInformation": "string",
  "PgpPublicKey": "string"
}

Properties

Name	Type	Required	Restrictions	Description
ContactId	string	false	none	Unique contact ID for the row.
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
ContactType	string	false	none	none
FirstName	string	false	none	none
LastName	string	false	none	none
Department	string	false	none	none
EmailAddress	string	false	none	none
PhoneNumber	string	false	none	none
AddressLine1	string	false	none	Address line 1
AddressLine2	string	false	none	Address line 2
City	string	false	none	City
Postcode	string	false	none	Postcode
Country	string	false	none	Country
AdditionalInformation	string	false	none	Any additional user information
PgpPublicKey	string	false	none	A PGP Public Key in text form

Enumerated Values

Property	Value
ContactType	Business
ContactType	Technical
ContactType	Billing
ContactType	Incident
ContactType	Security

ContactId

"string"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

OrganisationRequest

{
  "OrganisationId": "string",
  "Status": "Active",
  "OrganisationName": "string",
  "LegalEntityName": "string",
  "CountryOfRegistration": "string",
  "CompanyRegister": "string",
  "RegistrationNumber": "string",
  "RegistrationId": "string",
  "RegisteredName": "string",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "City": "string",
  "Postcode": "string",
  "Country": "string",
  "ParentOrganisationReference": "string"
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationId	OrganisationId	true	none	Unique ID associated with the organisation
Status	string	false	none	Status of the directory registration of an organisation
OrganisationName	string	true	none	none
LegalEntityName	string	true	none	Legal Entity name for the org. Usually the same as org name
CountryOfRegistration	string	true	none	Country of registration for the org
CompanyRegister	string	true	none	Legal company register for the country, i.e. Companies House
RegistrationNumber	string	true	none	Company registration number from company register i.e. Companies House registration number
RegistrationId	string	false	none	Registered ID for the organisation i.e. Legal Entity identifier number
RegisteredName	string	false	none	Registered legal name
AddressLine1	string	true	none	Address line 1
AddressLine2	string	false	none	Address line 2
City	string	true	none	City
Postcode	string	true	none	Postcode
Country	string	true	none	Country
ParentOrganisationReference	string	false	none	Parent Organisation Reference

Enumerated Values

Property	Value
Status	Active
Status	Pending
Status	Withdrawn

OrganisationUpdateRequest

{
  "Status": "Active",
  "OrganisationName": "string",
  "LegalEntityName": "string",
  "CountryOfRegistration": "string",
  "CompanyRegister": "string",
  "RegistrationNumber": "string",
  "RegistrationId": "string",
  "RegisteredName": "string",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "City": "string",
  "Postcode": "string",
  "Country": "string",
  "ParentOrganisationReference": "string"
}

Properties

Name	Type	Required	Restrictions	Description
Status	string	false	none	Status of the directory registration of an organisation
OrganisationName	string	true	none	none
LegalEntityName	string	true	none	Legal Entity name for the org. Usually the same as org name
CountryOfRegistration	string	true	none	Country of registration for the org
CompanyRegister	string	true	none	Legal company register for the country, i.e. Companies House
RegistrationNumber	string	true	none	Company registration number from company register i.e. Companies House registration number
RegistrationId	string	false	none	Registered ID for the organisation i.e. Legal Entity identifier number
RegisteredName	string	false	none	Registered legal name
AddressLine1	string	true	none	Address line 1
AddressLine2	string	false	none	Address line 2
City	string	true	none	City
Postcode	string	true	none	Postcode
Country	string	true	none	Country
ParentOrganisationReference	string	false	none	Parent Organisation Reference

Enumerated Values

Property	Value
Status	Active
Status	Pending
Status	Withdrawn

OrganisationEnrol

{
  "RedirectUris": [
    "http://example.com"
  ],
  "TokenEndpointAuthMethod": "string",
  "GrantTypes": [
    "string"
  ],
  "ResponseTypes": [
    "string"
  ],
  "ClientName": "string",
  "ClientUri": "http://example.com",
  "LogoUri": "http://example.com",
  "Scope": "string",
  "TosUri": "http://example.com",
  "PolicyUri": "http://example.com"
}

Properties

Name	Type	Required	Restrictions	Description
RedirectUris	[string]	true	none	none
TokenEndpointAuthMethod	string	true	none	none
GrantTypes	[string]	true	none	none
ResponseTypes	[string]	true	none	none
ClientName	number	true	none	ORG name as per eIDAS certificate
ClientUri	string(uri)	true	none	A compliant URI
LogoUri	string(uri)	true	none	A compliant URI
Scope	string	true	none	none
TosUri	string(uri)	true	none	A compliant URI
PolicyUri	string(uri)	true	none	A compliant URI

OrganisationEnrolments

[
  {
    "OrganisationId": "string",
    "ClientSecret": "string",
    "RedirectUris": [
      "http://example.com"
    ],
    "TokenEndpointAuthMethod": "string",
    "GrantTypes": [
      "string"
    ],
    "ResponseTypes": [
      "string"
    ],
    "ClientName": "string",
    "ClientUri": "http://example.com",
    "LogoUri": "http://example.com",
    "TosUri": "http://example.com",
    "PolicyUri": "http://example.com",
    "JwksUri": "http://example.com",
    "Jwks": {}
  }
]

A JSON object DCR response returned when client gets created.

Properties

Name	Type	Required	Restrictions	Description
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
ClientSecret	string	false	none	Client secret generated by Directory
RedirectUris	[string]	false	none	none
TokenEndpointAuthMethod	string	false	none	none
GrantTypes	[string]	false	none	none
ResponseTypes	[string]	false	none	none
ClientName	string	false	none	ORG name as per eIDAS certificate
ClientUri	string(uri)	false	none	A compliant URI string of a web page providing information about the client
LogoUri	string(uri)	false	none	A compliant URI
TosUri	string(uri)	false	none	A compliant URI string that points to a human-readable terms of service document for the client
PolicyUri	string(uri)	false	none	A compliant URI string that points to a human-readable privacy policy document
JwksUri	string(uri)	false	none	A compliant URI string referencing the client's JSON Web Key (JWK) Set
Jwks	object	false	none	Client's JSON Web Key Set [RFC7517] document value

OrganisationCertificateType

"qwac"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	qwac
anonymous	qseal
anonymous	rtswac
anonymous	rtsseal

OrganisationId

"string"

Unique ID associated with the organisation

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Unique ID associated with the organisation

OrganisationAuthorityClaimId

"string"

Unique ID associated with the authority claims

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Unique ID associated with the authority claims

OrganisationAuthorisationId

"string"

Unique ID associated with authorisations for organisation's authority claims

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Unique ID associated with authorisations for organisation's authority claims

SoftwareAuthorityClaimId

"string"

Unique ID associated with the authority claims for a software statement

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Unique ID associated with the authority claims for a software statement

AuthorityId

"string"

Unique ID associated with the Authorisation reference schema

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Unique ID associated with the Authorisation reference schema

Organisations

[
  {
    "OrganisationId": "string",
    "Status": "Active",
    "OrganisationName": "string",
    "CreatedOn": "string",
    "LegalEntityName": "string",
    "CountryOfRegistration": "string",
    "CompanyRegister": "string",
    "RegistrationNumber": "string",
    "RegistrationId": "string",
    "RegisteredName": "string",
    "AddressLine1": "string",
    "AddressLine2": "string",
    "City": "string",
    "Postcode": "string",
    "Country": "string",
    "ParentOrganisationReference": "string",
    "RequiresSigning": true,
    "TnCUpdated": true,
    "TnCsToBeSigned": [
      {
        "TnCId": 0,
        "Version": 0,
        "Name": "string",
        "Type": "string",
        "Content": "string",
        "Status": "Active",
        "ExternalSigningService": {
          "ExternalSigningServiceName": "DocuSign",
          "ExternalSigningServiceSignerTemplateConfig": {
            "TemplateIdSigner1": "string",
            "TemplateIdSigner2": "string",
            "TemplateIdSigner3": "string",
            "TemplateIdSigner4": "string",
            "TemplateIdSigner5": "string",
            "TemplateIdSigner6": "string"
          },
          "ExternalSigningServiceSubject": "string"
        }
      }
    ]
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[Organisation]	false	none	none

Organisation

{
  "OrganisationId": "string",
  "Status": "Active",
  "OrganisationName": "string",
  "CreatedOn": "string",
  "LegalEntityName": "string",
  "CountryOfRegistration": "string",
  "CompanyRegister": "string",
  "RegistrationNumber": "string",
  "RegistrationId": "string",
  "RegisteredName": "string",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "City": "string",
  "Postcode": "string",
  "Country": "string",
  "ParentOrganisationReference": "string",
  "RequiresSigning": true,
  "TnCUpdated": true,
  "TnCsToBeSigned": [
    {
      "TnCId": 0,
      "Version": 0,
      "Name": "string",
      "Type": "string",
      "Content": "string",
      "Status": "Active",
      "ExternalSigningService": {
        "ExternalSigningServiceName": "DocuSign",
        "ExternalSigningServiceSignerTemplateConfig": {
          "TemplateIdSigner1": "string",
          "TemplateIdSigner2": "string",
          "TemplateIdSigner3": "string",
          "TemplateIdSigner4": "string",
          "TemplateIdSigner5": "string",
          "TemplateIdSigner6": "string"
        },
        "ExternalSigningServiceSubject": "string"
      }
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
Status	string	false	none	Status of the directory registration of an organisation
OrganisationName	string	false	none	Name of the organisation.
CreatedOn	string	false	none	JSONDatetime of organisation creation.
LegalEntityName	string	false	none	Legal Entity name for the org. Usually the same as org name
CountryOfRegistration	string	false	none	Country of registration for the org
CompanyRegister	string	false	none	Legal company register for the country, i.e. Companies House
RegistrationNumber	string	false	none	Company registration number from company register i.e. Companies House registration number
RegistrationId	string	false	none	Registered ID for the organisation i.e. Legal Entity identifier number
RegisteredName	string	false	none	none
AddressLine1	string	false	none	Address line 1
AddressLine2	string	false	none	Address line 2
City	string	false	none	City
Postcode	string	false	none	Postcode
Country	string	false	none	Country
ParentOrganisationReference	string	false	none	Parent Organisation Reference
RequiresSigning	boolean	false	none	true - one of the attached tncs has to be signed. false - no tnc present
TnCUpdated	boolean	false	none	true - attached tnc has been update. false - no tnc present
TnCsToBeSigned	TnCsToBeSigned	false	none	none

Enumerated Values

Property	Value
Status	Active
Status	Pending
Status	Withdrawn

OrgTermsAndConditionsDetail

{
  "InitiatedBy": "string",
  "Role": "string",
  "TermsAndConditionsDetail": {
    "TermsAndConditionsItem": {
      "TnCId": 0,
      "Version": 0,
      "Name": "string",
      "Type": "string",
      "Content": "string",
      "Status": "Active",
      "ExternalSigningService": {
        "ExternalSigningServiceName": "DocuSign",
        "ExternalSigningServiceSignerTemplateConfig": {
          "TemplateIdSigner1": "string",
          "TemplateIdSigner2": "string",
          "TemplateIdSigner3": "string",
          "TemplateIdSigner4": "string",
          "TemplateIdSigner5": "string",
          "TemplateIdSigner6": "string"
        },
        "ExternalSigningServiceSubject": "string"
      }
    },
    "InititatedDate": "string",
    "ExternalSigningServiceEnvelopeId": "string",
    "ExternalSigningServiceEnvelopeStatus": "Completed",
    "ExternalSigningServiceEnvelopePasscode": "string"
  }
}

Participant TnC details

Properties

Name	Type	Required	Restrictions	Description
InitiatedBy	string	false	none	Email of the user who initiated the External signing for this participant
Role	string	false	none	Role of the user who initiated the External signing for this participant
TermsAndConditionsDetail	TermsAndConditionsDetail	false	none	TnC details Parent

TermsAndConditionsDetail

{
  "TermsAndConditionsItem": {
    "TnCId": 0,
    "Version": 0,
    "Name": "string",
    "Type": "string",
    "Content": "string",
    "Status": "Active",
    "ExternalSigningService": {
      "ExternalSigningServiceName": "DocuSign",
      "ExternalSigningServiceSignerTemplateConfig": {
        "TemplateIdSigner1": "string",
        "TemplateIdSigner2": "string",
        "TemplateIdSigner3": "string",
        "TemplateIdSigner4": "string",
        "TemplateIdSigner5": "string",
        "TemplateIdSigner6": "string"
      },
      "ExternalSigningServiceSubject": "string"
    }
  },
  "InititatedDate": "string",
  "ExternalSigningServiceEnvelopeId": "string",
  "ExternalSigningServiceEnvelopeStatus": "Completed",
  "ExternalSigningServiceEnvelopePasscode": "string"
}

TnC details Parent

Properties

Name	Type	Required	Restrictions	Description
TermsAndConditionsItem	TermsAndConditionsItem	false	none	none
InititatedDate	string	false	none	Terms and Conditions initiated date
ExternalSigningServiceEnvelopeId	ExternalSigningServiceEnvelopeId	false	none	The envelope id of the ess signing request
ExternalSigningServiceEnvelopeStatus	ExternalSigningServiceEnvelopeStatus	false	none	none
ExternalSigningServiceEnvelopePasscode	string	false	none	Access code for the specifier to fill in the signer details. This will be populated only once, when signing is initiated

ExternalSigningServiceEnvelopeStatus

"Completed"

Properties

None

OrganisationSnapshotPage

{
  "totalPages": 0,
  "totalSize": 0,
  "pageable": {
    "number": 0,
    "sort": {
      "sorted": true,
      "orderBy": [
        {
          "property": "createdAt",
          "direction": "ASC",
          "ignoreCase": true,
          "ascending": true
        }
      ]
    },
    "size": 0,
    "offset": 0,
    "sorted": true
  },
  "numberOfElements": 0,
  "size": 0,
  "content": [
    {
      "OrganisationDetails": {
        "OrganisationId": "string",
        "Status": "Active",
        "OrganisationName": "string",
        "CreatedOn": "string",
        "LegalEntityName": "string",
        "CountryOfRegistration": "string",
        "CompanyRegister": "string",
        "RegistrationNumber": "string",
        "RegistrationId": "string",
        "RegisteredName": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "City": "string",
        "Postcode": "string",
        "Country": "string",
        "ParentOrganisationReference": "string",
        "RequiresSigning": true,
        "TnCUpdated": true,
        "TnCsToBeSigned": [
          {
            "TnCId": 0,
            "Version": 0,
            "Name": "string",
            "Type": "string",
            "Content": "string",
            "Status": "Active",
            "ExternalSigningService": {
              "ExternalSigningServiceName": "DocuSign",
              "ExternalSigningServiceSignerTemplateConfig": {
                "TemplateIdSigner1": "string",
                "TemplateIdSigner2": "string",
                "TemplateIdSigner3": "string",
                "TemplateIdSigner4": "string",
                "TemplateIdSigner5": "string",
                "TemplateIdSigner6": "string"
              },
              "ExternalSigningServiceSubject": "string"
            }
          }
        ]
      },
      "Contacts": [
        {
          "ContactId": "string",
          "OrganisationId": "string",
          "ContactType": "Business",
          "FirstName": "string",
          "LastName": "string",
          "Department": "string",
          "EmailAddress": "string",
          "PhoneNumber": "string",
          "AddressLine1": "string",
          "AddressLine2": "string",
          "City": "string",
          "Postcode": "string",
          "Country": "string",
          "AdditionalInformation": "string",
          "PgpPublicKey": "string"
        }
      ],
      "AuthorisationServers": [
        {
          "AuthorisationServerId": "string",
          "OrganisationId": "string",
          "AutoRegistrationSupported": true,
          "ApiResources": [
            {
              "ApiResourceId": "string",
              "ApiFamilyType": "string",
              "ApiVersion": 0,
              "ApiDiscoveryEndpoints": [
                {
                  "ApiDiscoveryId": "string",
                  "ApiEndpoint": "http://example.com"
                }
              ]
            }
          ],
          "CustomerFriendlyDescription": "string",
          "CustomerFriendlyLogoUri": "http://example.com",
          "CustomerFriendlyName": "string",
          "DeveloperPortalUri": "http://example.com",
          "TermsOfServiceUri": "http://example.com",
          "NotificationWebhook": "http://example.com",
          "NotificationWebhookStatus": "string",
          "OpenIDDiscoveryDocument": "http://example.com",
          "PayloadSigningCertLocationUri": "http://example.com",
          "ParentAuthorisationServerId": "string"
        }
      ],
      "OrgDomainClaims": [
        {
          "OrganisationAuthorityDomainClaimId": "string",
          "AuthorisationDomainName": "string",
          "AuthorityId": "string",
          "AuthorityName": "string",
          "RegistrationId": "string",
          "Status": "Active"
        }
      ],
      "OrgDomainRoleClaims": [
        {
          "OrganisationId": "string",
          "OrganisationAuthorityClaimId": "string",
          "AuthorityId": "string",
          "Status": "Active",
          "AuthorisationDomain": "string",
          "Role": "string",
          "Authorisations": [
            {
              "Status": "Active",
              "MemberState": "st"
            }
          ],
          "RegistrationId": "string",
          "UniqueTechnicalIdenifier": [
            "string"
          ]
        }
      ],
      "SoftwareStatements": {
        "property1": {
          "SoftwareDetails": {
            "Status": "Active",
            "ClientId": "string",
            "ClientName": "string",
            "Description": "string",
            "Environment": "string",
            "OrganisationId": "string",
            "SoftwareStatementId": "string",
            "Mode": "Live",
            "RtsClientCreated": true,
            "OnBehalfOf": "string",
            "PolicyUri": "string",
            "ClientUri": "string",
            "LogoUri": "http://example.com",
            "RedirectUri": [
              "http://example.com"
            ],
            "TermsOfServiceUri": "http://example.com",
            "Version": 0,
            "Locked": true
          },
          "SoftwareAuthorityClaims": [
            {
              "SoftwareStatementId": "string",
              "SoftwareAuthorityClaimId": "string",
              "Status": "Active",
              "AuthorisationDomain": "string",
              "Role": "string"
            }
          ],
          "SoftwareCertificates": [
            {
              "OrganisationId": "string",
              "SoftwareStatementIds": [
                "string"
              ],
              "ClientName": "string",
              "Status": "string",
              "ValidFromDateTime": "string",
              "ExpiryDateTime": "string",
              "e": "string",
              "keyType": "string",
              "kid": "string",
              "kty": "string",
              "n": "string",
              "use": "string",
              "x5c": [
                "string"
              ],
              "x5t": "string",
              "x5thashS256": "string",
              "x5u": "string",
              "SignedCertPath": "string",
              "JwkPath": "string",
              "OrgJwkPath": "string"
            }
          ]
        },
        "property2": {
          "SoftwareDetails": {
            "Status": "Active",
            "ClientId": "string",
            "ClientName": "string",
            "Description": "string",
            "Environment": "string",
            "OrganisationId": "string",
            "SoftwareStatementId": "string",
            "Mode": "Live",
            "RtsClientCreated": true,
            "OnBehalfOf": "string",
            "PolicyUri": "string",
            "ClientUri": "string",
            "LogoUri": "http://example.com",
            "RedirectUri": [
              "http://example.com"
            ],
            "TermsOfServiceUri": "http://example.com",
            "Version": 0,
            "Locked": true
          },
          "SoftwareAuthorityClaims": [
            {
              "SoftwareStatementId": "string",
              "SoftwareAuthorityClaimId": "string",
              "Status": "Active",
              "AuthorisationDomain": "string",
              "Role": "string"
            }
          ],
          "SoftwareCertificates": [
            {
              "OrganisationId": "string",
              "SoftwareStatementIds": [
                "string"
              ],
              "ClientName": "string",
              "Status": "string",
              "ValidFromDateTime": "string",
              "ExpiryDateTime": "string",
              "e": "string",
              "keyType": "string",
              "kid": "string",
              "kty": "string",
              "n": "string",
              "use": "string",
              "x5c": [
                "string"
              ],
              "x5t": "string",
              "x5thashS256": "string",
              "x5u": "string",
              "SignedCertPath": "string",
              "JwkPath": "string",
              "OrgJwkPath": "string"
            }
          ]
        }
      }
    }
  ],
  "offset": 0,
  "empty": true,
  "pageNumber": 0
}

Properties

Name	Type	Required	Restrictions	Description
totalPages	integer	false	none	none
totalSize	integer	false	none	none
pageable	Pageable	false	none	none
numberOfElements	integer	false	none	none
size	integer	false	none	none
content	[OrganisationSnapshot]	false	none	none
offset	integer	false	none	none
empty	boolean	false	none	none
pageNumber	integer	false	none	none

Pageable

{
  "number": 0,
  "sort": {
    "sorted": true,
    "orderBy": [
      {
        "property": "createdAt",
        "direction": "ASC",
        "ignoreCase": true,
        "ascending": true
      }
    ]
  },
  "size": 0,
  "offset": 0,
  "sorted": true
}

Properties

Name	Type	Required	Restrictions	Description
number	integer	false	none	Page number
sort	Sort	false	none	none
size	integer	false	none	Size of the page
offset	integer	false	none	Offset
sorted	boolean	false	none	Is the page sorted

Sort

{
  "sorted": true,
  "orderBy": [
    {
      "property": "createdAt",
      "direction": "ASC",
      "ignoreCase": true,
      "ascending": true
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
sorted	boolean	false	none	none
orderBy	[object]	false	none	none
» property	string	false	none	Name of the property used for sorting
» direction	string	false	none	Direction of sort, i.e. ascending or descending
» ignoreCase	boolean	false	none	Was the case ignored
» ascending	boolean	false	none	Whether ascending

Enumerated Values

Property	Value
direction	ASC
direction	DESC

OrganisationsSnapshot

{
  "property1": {
    "OrganisationDetails": {
      "OrganisationId": "string",
      "Status": "Active",
      "OrganisationName": "string",
      "CreatedOn": "string",
      "LegalEntityName": "string",
      "CountryOfRegistration": "string",
      "CompanyRegister": "string",
      "RegistrationNumber": "string",
      "RegistrationId": "string",
      "RegisteredName": "string",
      "AddressLine1": "string",
      "AddressLine2": "string",
      "City": "string",
      "Postcode": "string",
      "Country": "string",
      "ParentOrganisationReference": "string",
      "RequiresSigning": true,
      "TnCUpdated": true,
      "TnCsToBeSigned": [
        {
          "TnCId": 0,
          "Version": 0,
          "Name": "string",
          "Type": "string",
          "Content": "string",
          "Status": "Active",
          "ExternalSigningService": {
            "ExternalSigningServiceName": "DocuSign",
            "ExternalSigningServiceSignerTemplateConfig": {
              "TemplateIdSigner1": "string",
              "TemplateIdSigner2": "string",
              "TemplateIdSigner3": "string",
              "TemplateIdSigner4": "string",
              "TemplateIdSigner5": "string",
              "TemplateIdSigner6": "string"
            },
            "ExternalSigningServiceSubject": "string"
          }
        }
      ]
    },
    "Contacts": [
      {
        "ContactId": "string",
        "OrganisationId": "string",
        "ContactType": "Business",
        "FirstName": "string",
        "LastName": "string",
        "Department": "string",
        "EmailAddress": "string",
        "PhoneNumber": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "City": "string",
        "Postcode": "string",
        "Country": "string",
        "AdditionalInformation": "string",
        "PgpPublicKey": "string"
      }
    ],
    "AuthorisationServers": [
      {
        "AuthorisationServerId": "string",
        "OrganisationId": "string",
        "AutoRegistrationSupported": true,
        "ApiResources": [
          {
            "ApiResourceId": "string",
            "ApiFamilyType": "string",
            "ApiVersion": 0,
            "ApiDiscoveryEndpoints": [
              {
                "ApiDiscoveryId": "string",
                "ApiEndpoint": "http://example.com"
              }
            ]
          }
        ],
        "CustomerFriendlyDescription": "string",
        "CustomerFriendlyLogoUri": "http://example.com",
        "CustomerFriendlyName": "string",
        "DeveloperPortalUri": "http://example.com",
        "TermsOfServiceUri": "http://example.com",
        "NotificationWebhook": "http://example.com",
        "NotificationWebhookStatus": "string",
        "OpenIDDiscoveryDocument": "http://example.com",
        "PayloadSigningCertLocationUri": "http://example.com",
        "ParentAuthorisationServerId": "string"
      }
    ],
    "OrgDomainClaims": [
      {
        "OrganisationAuthorityDomainClaimId": "string",
        "AuthorisationDomainName": "string",
        "AuthorityId": "string",
        "AuthorityName": "string",
        "RegistrationId": "string",
        "Status": "Active"
      }
    ],
    "OrgDomainRoleClaims": [
      {
        "OrganisationId": "string",
        "OrganisationAuthorityClaimId": "string",
        "AuthorityId": "string",
        "Status": "Active",
        "AuthorisationDomain": "string",
        "Role": "string",
        "Authorisations": [
          {
            "Status": "Active",
            "MemberState": "st"
          }
        ],
        "RegistrationId": "string",
        "UniqueTechnicalIdenifier": [
          "string"
        ]
      }
    ],
    "SoftwareStatements": {
      "property1": {
        "SoftwareDetails": {
          "Status": "Active",
          "ClientId": "string",
          "ClientName": "string",
          "Description": "string",
          "Environment": "string",
          "OrganisationId": "string",
          "SoftwareStatementId": "string",
          "Mode": "Live",
          "RtsClientCreated": true,
          "OnBehalfOf": "string",
          "PolicyUri": "string",
          "ClientUri": "string",
          "LogoUri": "http://example.com",
          "RedirectUri": [
            "http://example.com"
          ],
          "TermsOfServiceUri": "http://example.com",
          "Version": 0,
          "Locked": true
        },
        "SoftwareAuthorityClaims": [
          {
            "SoftwareStatementId": "string",
            "SoftwareAuthorityClaimId": "string",
            "Status": "Active",
            "AuthorisationDomain": "string",
            "Role": "string"
          }
        ],
        "SoftwareCertificates": [
          {
            "OrganisationId": "string",
            "SoftwareStatementIds": [
              "string"
            ],
            "ClientName": "string",
            "Status": "string",
            "ValidFromDateTime": "string",
            "ExpiryDateTime": "string",
            "e": "string",
            "keyType": "string",
            "kid": "string",
            "kty": "string",
            "n": "string",
            "use": "string",
            "x5c": [
              "string"
            ],
            "x5t": "string",
            "x5thashS256": "string",
            "x5u": "string",
            "SignedCertPath": "string",
            "JwkPath": "string",
            "OrgJwkPath": "string"
          }
        ]
      },
      "property2": {
        "SoftwareDetails": {
          "Status": "Active",
          "ClientId": "string",
          "ClientName": "string",
          "Description": "string",
          "Environment": "string",
          "OrganisationId": "string",
          "SoftwareStatementId": "string",
          "Mode": "Live",
          "RtsClientCreated": true,
          "OnBehalfOf": "string",
          "PolicyUri": "string",
          "ClientUri": "string",
          "LogoUri": "http://example.com",
          "RedirectUri": [
            "http://example.com"
          ],
          "TermsOfServiceUri": "http://example.com",
          "Version": 0,
          "Locked": true
        },
        "SoftwareAuthorityClaims": [
          {
            "SoftwareStatementId": "string",
            "SoftwareAuthorityClaimId": "string",
            "Status": "Active",
            "AuthorisationDomain": "string",
            "Role": "string"
          }
        ],
        "SoftwareCertificates": [
          {
            "OrganisationId": "string",
            "SoftwareStatementIds": [
              "string"
            ],
            "ClientName": "string",
            "Status": "string",
            "ValidFromDateTime": "string",
            "ExpiryDateTime": "string",
            "e": "string",
            "keyType": "string",
            "kid": "string",
            "kty": "string",
            "n": "string",
            "use": "string",
            "x5c": [
              "string"
            ],
            "x5t": "string",
            "x5thashS256": "string",
            "x5u": "string",
            "SignedCertPath": "string",
            "JwkPath": "string",
            "OrgJwkPath": "string"
          }
        ]
      }
    }
  },
  "property2": {
    "OrganisationDetails": {
      "OrganisationId": "string",
      "Status": "Active",
      "OrganisationName": "string",
      "CreatedOn": "string",
      "LegalEntityName": "string",
      "CountryOfRegistration": "string",
      "CompanyRegister": "string",
      "RegistrationNumber": "string",
      "RegistrationId": "string",
      "RegisteredName": "string",
      "AddressLine1": "string",
      "AddressLine2": "string",
      "City": "string",
      "Postcode": "string",
      "Country": "string",
      "ParentOrganisationReference": "string",
      "RequiresSigning": true,
      "TnCUpdated": true,
      "TnCsToBeSigned": [
        {
          "TnCId": 0,
          "Version": 0,
          "Name": "string",
          "Type": "string",
          "Content": "string",
          "Status": "Active",
          "ExternalSigningService": {
            "ExternalSigningServiceName": "DocuSign",
            "ExternalSigningServiceSignerTemplateConfig": {
              "TemplateIdSigner1": "string",
              "TemplateIdSigner2": "string",
              "TemplateIdSigner3": "string",
              "TemplateIdSigner4": "string",
              "TemplateIdSigner5": "string",
              "TemplateIdSigner6": "string"
            },
            "ExternalSigningServiceSubject": "string"
          }
        }
      ]
    },
    "Contacts": [
      {
        "ContactId": "string",
        "OrganisationId": "string",
        "ContactType": "Business",
        "FirstName": "string",
        "LastName": "string",
        "Department": "string",
        "EmailAddress": "string",
        "PhoneNumber": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "City": "string",
        "Postcode": "string",
        "Country": "string",
        "AdditionalInformation": "string",
        "PgpPublicKey": "string"
      }
    ],
    "AuthorisationServers": [
      {
        "AuthorisationServerId": "string",
        "OrganisationId": "string",
        "AutoRegistrationSupported": true,
        "ApiResources": [
          {
            "ApiResourceId": "string",
            "ApiFamilyType": "string",
            "ApiVersion": 0,
            "ApiDiscoveryEndpoints": [
              {
                "ApiDiscoveryId": "string",
                "ApiEndpoint": "http://example.com"
              }
            ]
          }
        ],
        "CustomerFriendlyDescription": "string",
        "CustomerFriendlyLogoUri": "http://example.com",
        "CustomerFriendlyName": "string",
        "DeveloperPortalUri": "http://example.com",
        "TermsOfServiceUri": "http://example.com",
        "NotificationWebhook": "http://example.com",
        "NotificationWebhookStatus": "string",
        "OpenIDDiscoveryDocument": "http://example.com",
        "PayloadSigningCertLocationUri": "http://example.com",
        "ParentAuthorisationServerId": "string"
      }
    ],
    "OrgDomainClaims": [
      {
        "OrganisationAuthorityDomainClaimId": "string",
        "AuthorisationDomainName": "string",
        "AuthorityId": "string",
        "AuthorityName": "string",
        "RegistrationId": "string",
        "Status": "Active"
      }
    ],
    "OrgDomainRoleClaims": [
      {
        "OrganisationId": "string",
        "OrganisationAuthorityClaimId": "string",
        "AuthorityId": "string",
        "Status": "Active",
        "AuthorisationDomain": "string",
        "Role": "string",
        "Authorisations": [
          {
            "Status": "Active",
            "MemberState": "st"
          }
        ],
        "RegistrationId": "string",
        "UniqueTechnicalIdenifier": [
          "string"
        ]
      }
    ],
    "SoftwareStatements": {
      "property1": {
        "SoftwareDetails": {
          "Status": "Active",
          "ClientId": "string",
          "ClientName": "string",
          "Description": "string",
          "Environment": "string",
          "OrganisationId": "string",
          "SoftwareStatementId": "string",
          "Mode": "Live",
          "RtsClientCreated": true,
          "OnBehalfOf": "string",
          "PolicyUri": "string",
          "ClientUri": "string",
          "LogoUri": "http://example.com",
          "RedirectUri": [
            "http://example.com"
          ],
          "TermsOfServiceUri": "http://example.com",
          "Version": 0,
          "Locked": true
        },
        "SoftwareAuthorityClaims": [
          {
            "SoftwareStatementId": "string",
            "SoftwareAuthorityClaimId": "string",
            "Status": "Active",
            "AuthorisationDomain": "string",
            "Role": "string"
          }
        ],
        "SoftwareCertificates": [
          {
            "OrganisationId": "string",
            "SoftwareStatementIds": [
              "string"
            ],
            "ClientName": "string",
            "Status": "string",
            "ValidFromDateTime": "string",
            "ExpiryDateTime": "string",
            "e": "string",
            "keyType": "string",
            "kid": "string",
            "kty": "string",
            "n": "string",
            "use": "string",
            "x5c": [
              "string"
            ],
            "x5t": "string",
            "x5thashS256": "string",
            "x5u": "string",
            "SignedCertPath": "string",
            "JwkPath": "string",
            "OrgJwkPath": "string"
          }
        ]
      },
      "property2": {
        "SoftwareDetails": {
          "Status": "Active",
          "ClientId": "string",
          "ClientName": "string",
          "Description": "string",
          "Environment": "string",
          "OrganisationId": "string",
          "SoftwareStatementId": "string",
          "Mode": "Live",
          "RtsClientCreated": true,
          "OnBehalfOf": "string",
          "PolicyUri": "string",
          "ClientUri": "string",
          "LogoUri": "http://example.com",
          "RedirectUri": [
            "http://example.com"
          ],
          "TermsOfServiceUri": "http://example.com",
          "Version": 0,
          "Locked": true
        },
        "SoftwareAuthorityClaims": [
          {
            "SoftwareStatementId": "string",
            "SoftwareAuthorityClaimId": "string",
            "Status": "Active",
            "AuthorisationDomain": "string",
            "Role": "string"
          }
        ],
        "SoftwareCertificates": [
          {
            "OrganisationId": "string",
            "SoftwareStatementIds": [
              "string"
            ],
            "ClientName": "string",
            "Status": "string",
            "ValidFromDateTime": "string",
            "ExpiryDateTime": "string",
            "e": "string",
            "keyType": "string",
            "kid": "string",
            "kty": "string",
            "n": "string",
            "use": "string",
            "x5c": [
              "string"
            ],
            "x5t": "string",
            "x5thashS256": "string",
            "x5u": "string",
            "SignedCertPath": "string",
            "JwkPath": "string",
            "OrgJwkPath": "string"
          }
        ]
      }
    }
  }
}

Properties

Name	Type	Required	Restrictions	Description
additionalProperties	OrganisationSnapshot	false	none	none

OrganisationSnapshot

{
  "OrganisationDetails": {
    "OrganisationId": "string",
    "Status": "Active",
    "OrganisationName": "string",
    "CreatedOn": "string",
    "LegalEntityName": "string",
    "CountryOfRegistration": "string",
    "CompanyRegister": "string",
    "RegistrationNumber": "string",
    "RegistrationId": "string",
    "RegisteredName": "string",
    "AddressLine1": "string",
    "AddressLine2": "string",
    "City": "string",
    "Postcode": "string",
    "Country": "string",
    "ParentOrganisationReference": "string",
    "RequiresSigning": true,
    "TnCUpdated": true,
    "TnCsToBeSigned": [
      {
        "TnCId": 0,
        "Version": 0,
        "Name": "string",
        "Type": "string",
        "Content": "string",
        "Status": "Active",
        "ExternalSigningService": {
          "ExternalSigningServiceName": "DocuSign",
          "ExternalSigningServiceSignerTemplateConfig": {
            "TemplateIdSigner1": "string",
            "TemplateIdSigner2": "string",
            "TemplateIdSigner3": "string",
            "TemplateIdSigner4": "string",
            "TemplateIdSigner5": "string",
            "TemplateIdSigner6": "string"
          },
          "ExternalSigningServiceSubject": "string"
        }
      }
    ]
  },
  "Contacts": [
    {
      "ContactId": "string",
      "OrganisationId": "string",
      "ContactType": "Business",
      "FirstName": "string",
      "LastName": "string",
      "Department": "string",
      "EmailAddress": "string",
      "PhoneNumber": "string",
      "AddressLine1": "string",
      "AddressLine2": "string",
      "City": "string",
      "Postcode": "string",
      "Country": "string",
      "AdditionalInformation": "string",
      "PgpPublicKey": "string"
    }
  ],
  "AuthorisationServers": [
    {
      "AuthorisationServerId": "string",
      "OrganisationId": "string",
      "AutoRegistrationSupported": true,
      "ApiResources": [
        {
          "ApiResourceId": "string",
          "ApiFamilyType": "string",
          "ApiVersion": 0,
          "ApiDiscoveryEndpoints": [
            {
              "ApiDiscoveryId": "string",
              "ApiEndpoint": "http://example.com"
            }
          ]
        }
      ],
      "CustomerFriendlyDescription": "string",
      "CustomerFriendlyLogoUri": "http://example.com",
      "CustomerFriendlyName": "string",
      "DeveloperPortalUri": "http://example.com",
      "TermsOfServiceUri": "http://example.com",
      "NotificationWebhook": "http://example.com",
      "NotificationWebhookStatus": "string",
      "OpenIDDiscoveryDocument": "http://example.com",
      "PayloadSigningCertLocationUri": "http://example.com",
      "ParentAuthorisationServerId": "string"
    }
  ],
  "OrgDomainClaims": [
    {
      "OrganisationAuthorityDomainClaimId": "string",
      "AuthorisationDomainName": "string",
      "AuthorityId": "string",
      "AuthorityName": "string",
      "RegistrationId": "string",
      "Status": "Active"
    }
  ],
  "OrgDomainRoleClaims": [
    {
      "OrganisationId": "string",
      "OrganisationAuthorityClaimId": "string",
      "AuthorityId": "string",
      "Status": "Active",
      "AuthorisationDomain": "string",
      "Role": "string",
      "Authorisations": [
        {
          "Status": "Active",
          "MemberState": "st"
        }
      ],
      "RegistrationId": "string",
      "UniqueTechnicalIdenifier": [
        "string"
      ]
    }
  ],
  "SoftwareStatements": {
    "property1": {
      "SoftwareDetails": {
        "Status": "Active",
        "ClientId": "string",
        "ClientName": "string",
        "Description": "string",
        "Environment": "string",
        "OrganisationId": "string",
        "SoftwareStatementId": "string",
        "Mode": "Live",
        "RtsClientCreated": true,
        "OnBehalfOf": "string",
        "PolicyUri": "string",
        "ClientUri": "string",
        "LogoUri": "http://example.com",
        "RedirectUri": [
          "http://example.com"
        ],
        "TermsOfServiceUri": "http://example.com",
        "Version": 0,
        "Locked": true
      },
      "SoftwareAuthorityClaims": [
        {
          "SoftwareStatementId": "string",
          "SoftwareAuthorityClaimId": "string",
          "Status": "Active",
          "AuthorisationDomain": "string",
          "Role": "string"
        }
      ],
      "SoftwareCertificates": [
        {
          "OrganisationId": "string",
          "SoftwareStatementIds": [
            "string"
          ],
          "ClientName": "string",
          "Status": "string",
          "ValidFromDateTime": "string",
          "ExpiryDateTime": "string",
          "e": "string",
          "keyType": "string",
          "kid": "string",
          "kty": "string",
          "n": "string",
          "use": "string",
          "x5c": [
            "string"
          ],
          "x5t": "string",
          "x5thashS256": "string",
          "x5u": "string",
          "SignedCertPath": "string",
          "JwkPath": "string",
          "OrgJwkPath": "string"
        }
      ]
    },
    "property2": {
      "SoftwareDetails": {
        "Status": "Active",
        "ClientId": "string",
        "ClientName": "string",
        "Description": "string",
        "Environment": "string",
        "OrganisationId": "string",
        "SoftwareStatementId": "string",
        "Mode": "Live",
        "RtsClientCreated": true,
        "OnBehalfOf": "string",
        "PolicyUri": "string",
        "ClientUri": "string",
        "LogoUri": "http://example.com",
        "RedirectUri": [
          "http://example.com"
        ],
        "TermsOfServiceUri": "http://example.com",
        "Version": 0,
        "Locked": true
      },
      "SoftwareAuthorityClaims": [
        {
          "SoftwareStatementId": "string",
          "SoftwareAuthorityClaimId": "string",
          "Status": "Active",
          "AuthorisationDomain": "string",
          "Role": "string"
        }
      ],
      "SoftwareCertificates": [
        {
          "OrganisationId": "string",
          "SoftwareStatementIds": [
            "string"
          ],
          "ClientName": "string",
          "Status": "string",
          "ValidFromDateTime": "string",
          "ExpiryDateTime": "string",
          "e": "string",
          "keyType": "string",
          "kid": "string",
          "kty": "string",
          "n": "string",
          "use": "string",
          "x5c": [
            "string"
          ],
          "x5t": "string",
          "x5thashS256": "string",
          "x5u": "string",
          "SignedCertPath": "string",
          "JwkPath": "string",
          "OrgJwkPath": "string"
        }
      ]
    }
  }
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationDetails	Organisation	false	none	none
Contacts	Contacts	false	none	The list of contacts
AuthorisationServers	AuthorisationServers	false	none	none
OrgDomainClaims	OrganisationAuthorityDomainClaims	false	none	none
OrgDomainRoleClaims	OrganisationAuthorityClaims	false	none	none
SoftwareStatements	object	false	none	none
» additionalProperties	object	false	none	none
»» SoftwareDetails	SoftwareStatement	false	none	none
»» SoftwareAuthorityClaims	SoftwareAuthorityClaims	false	none	none
»» SoftwareCertificates	CertificatesOrKeys	false	none	none

OrganisationsExportOpenData

[
  {
    "OrganisationId": "string",
    "Status": "Active",
    "OrganisationName": "string",
    "CreatedOn": "string",
    "LegalEntityName": "string",
    "CountryOfRegistration": "string",
    "CompanyRegister": "string",
    "RegistrationNumber": "string",
    "RegistrationId": "string",
    "RegisteredName": "string",
    "AddressLine1": "string",
    "AddressLine2": "string",
    "City": "string",
    "Postcode": "string",
    "Country": "string",
    "ParentOrganisationReference": "string",
    "Contacts": [
      {
        "ContactId": "string",
        "OrganisationId": "string",
        "ContactType": "Business",
        "FirstName": "string",
        "LastName": "string",
        "Department": "string",
        "EmailAddress": "string",
        "PhoneNumber": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "City": "string",
        "Postcode": "string",
        "Country": "string",
        "AdditionalInformation": "string",
        "PgpPublicKey": "string"
      }
    ],
    "AuthorisationServers": [
      {
        "AuthorisationServerId": "string",
        "OrganisationId": "string",
        "AutoRegistrationSupported": true,
        "ApiResources": [
          {
            "ApiResourceId": "string",
            "ApiFamilyType": "string",
            "ApiVersion": 0,
            "ApiDiscoveryEndpoints": [
              {
                "ApiDiscoveryId": "string",
                "ApiEndpoint": "http://example.com"
              }
            ]
          }
        ],
        "CustomerFriendlyDescription": "string",
        "CustomerFriendlyLogoUri": "http://example.com",
        "CustomerFriendlyName": "string",
        "DeveloperPortalUri": "http://example.com",
        "TermsOfServiceUri": "http://example.com",
        "NotificationWebhook": "http://example.com",
        "NotificationWebhookStatus": "string",
        "OpenIDDiscoveryDocument": "http://example.com",
        "PayloadSigningCertLocationUri": "http://example.com",
        "ParentAuthorisationServerId": "string"
      }
    ],
    "OrgDomainClaims": [
      {
        "OrganisationAuthorityDomainClaimId": "string",
        "AuthorisationDomainName": "string",
        "AuthorityId": "string",
        "AuthorityName": "string",
        "RegistrationId": "string",
        "Status": "Active"
      }
    ],
    "OrgDomainRoleClaims": [
      {
        "OrganisationId": "string",
        "OrganisationAuthorityClaimId": "string",
        "AuthorityId": "string",
        "Status": "Active",
        "AuthorisationDomain": "string",
        "Role": "string",
        "Authorisations": [
          {
            "Status": "Active",
            "MemberState": "st"
          }
        ],
        "RegistrationId": "string",
        "UniqueTechnicalIdenifier": [
          "string"
        ]
      }
    ]
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[OrganisationExportOpenData]	false	none	none

OrganisationExportOpenData

{
  "OrganisationId": "string",
  "Status": "Active",
  "OrganisationName": "string",
  "CreatedOn": "string",
  "LegalEntityName": "string",
  "CountryOfRegistration": "string",
  "CompanyRegister": "string",
  "RegistrationNumber": "string",
  "RegistrationId": "string",
  "RegisteredName": "string",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "City": "string",
  "Postcode": "string",
  "Country": "string",
  "ParentOrganisationReference": "string",
  "Contacts": [
    {
      "ContactId": "string",
      "OrganisationId": "string",
      "ContactType": "Business",
      "FirstName": "string",
      "LastName": "string",
      "Department": "string",
      "EmailAddress": "string",
      "PhoneNumber": "string",
      "AddressLine1": "string",
      "AddressLine2": "string",
      "City": "string",
      "Postcode": "string",
      "Country": "string",
      "AdditionalInformation": "string",
      "PgpPublicKey": "string"
    }
  ],
  "AuthorisationServers": [
    {
      "AuthorisationServerId": "string",
      "OrganisationId": "string",
      "AutoRegistrationSupported": true,
      "ApiResources": [
        {
          "ApiResourceId": "string",
          "ApiFamilyType": "string",
          "ApiVersion": 0,
          "ApiDiscoveryEndpoints": [
            {
              "ApiDiscoveryId": "string",
              "ApiEndpoint": "http://example.com"
            }
          ]
        }
      ],
      "CustomerFriendlyDescription": "string",
      "CustomerFriendlyLogoUri": "http://example.com",
      "CustomerFriendlyName": "string",
      "DeveloperPortalUri": "http://example.com",
      "TermsOfServiceUri": "http://example.com",
      "NotificationWebhook": "http://example.com",
      "NotificationWebhookStatus": "string",
      "OpenIDDiscoveryDocument": "http://example.com",
      "PayloadSigningCertLocationUri": "http://example.com",
      "ParentAuthorisationServerId": "string"
    }
  ],
  "OrgDomainClaims": [
    {
      "OrganisationAuthorityDomainClaimId": "string",
      "AuthorisationDomainName": "string",
      "AuthorityId": "string",
      "AuthorityName": "string",
      "RegistrationId": "string",
      "Status": "Active"
    }
  ],
  "OrgDomainRoleClaims": [
    {
      "OrganisationId": "string",
      "OrganisationAuthorityClaimId": "string",
      "AuthorityId": "string",
      "Status": "Active",
      "AuthorisationDomain": "string",
      "Role": "string",
      "Authorisations": [
        {
          "Status": "Active",
          "MemberState": "st"
        }
      ],
      "RegistrationId": "string",
      "UniqueTechnicalIdenifier": [
        "string"
      ]
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
Status	string	false	none	Status of the directory registration of an organisation
OrganisationName	string	false	none	Name of the organisation.
CreatedOn	string	false	none	JSONDatetime of organisation creation.
LegalEntityName	string	false	none	Legal Entity name for the org. Usually the same as org name
CountryOfRegistration	string	false	none	Country of registration for the org
CompanyRegister	string	false	none	Legal company register for the country, i.e. Companies House
RegistrationNumber	string	false	none	Company registration number from company register i.e. Companies House registration number
RegistrationId	string	false	none	Registered ID for the organisation i.e. Legal Entity identifier number
RegisteredName	string	false	none	none
AddressLine1	string	false	none	Address line 1
AddressLine2	string	false	none	Address line 2
City	string	false	none	City
Postcode	string	false	none	Postcode
Country	string	false	none	Country
ParentOrganisationReference	string	false	none	Parent Organisation Reference
Contacts	Contacts	false	none	The list of contacts
AuthorisationServers	AuthorisationServers	false	none	none
OrgDomainClaims	OrganisationAuthorityDomainClaims	false	none	none
OrgDomainRoleClaims	OrganisationAuthorityClaims	false	none	none

Enumerated Values

Property	Value
Status	Active
Status	Pending
Status	Withdrawn

Authorities

[
  {
    "AuthorityId": "string",
    "AuthorityName": "string",
    "AuthorityCode": "string",
    "AuthorityUri": "string",
    "AuthorityCountry": "string",
    "Status": "Active"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[Authority]	false	none	none

Authority

{
  "AuthorityId": "string",
  "AuthorityName": "string",
  "AuthorityCode": "string",
  "AuthorityUri": "string",
  "AuthorityCountry": "string",
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorityId	AuthorityId	false	none	Unique ID associated with the Authorisation reference schema
AuthorityName	string	false	none	Name of the Authority i.e. FCA, etc
AuthorityCode	string	false	none	Code of the Authority i.e. FCA, etc
AuthorityUri	string	false	none	URI of the authority
AuthorityCountry	string	false	none	country of the Authority
Status	string	false	none	Is this Authority Active/Inactive

Enumerated Values

Property	Value
Status	Active
Status	Inactive

AuthorityRequest

{
  "AuthorityName": "string",
  "AuthorityCode": "string",
  "AuthorityUri": "string",
  "AuthorityCountry": "string"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorityName	string	true	none	The ID of the Authority i.e GBFCA, etc
AuthorityCode	string	true	none	Code of the Authority i.e. GBFCA, etc
AuthorityUri	string	true	none	URI of the authority
AuthorityCountry	string	true	none	Country of the authority

SoftwareStatementCertificateOrKeyType

"rtstransport"

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	none

Enumerated Values

Property	Value
anonymous	rtstransport
anonymous	rtssigning
anonymous	sigkey
anonymous	enckey

SoftwareStatements

[
  {
    "Status": "Active",
    "ClientId": "string",
    "ClientName": "string",
    "Description": "string",
    "Environment": "string",
    "OrganisationId": "string",
    "SoftwareStatementId": "string",
    "Mode": "Live",
    "RtsClientCreated": true,
    "OnBehalfOf": "string",
    "PolicyUri": "string",
    "ClientUri": "string",
    "LogoUri": "http://example.com",
    "RedirectUri": [
      "http://example.com"
    ],
    "TermsOfServiceUri": "http://example.com",
    "Version": 0,
    "Locked": true
  }
]

The list of Software Statements

Properties

Name	Type	Required	Restrictions	Description
anonymous	[SoftwareStatement]	false	none	The list of Software Statements

SoftwareStatement

{
  "Status": "Active",
  "ClientId": "string",
  "ClientName": "string",
  "Description": "string",
  "Environment": "string",
  "OrganisationId": "string",
  "SoftwareStatementId": "string",
  "Mode": "Live",
  "RtsClientCreated": true,
  "OnBehalfOf": "string",
  "PolicyUri": "string",
  "ClientUri": "string",
  "LogoUri": "http://example.com",
  "RedirectUri": [
    "http://example.com"
  ],
  "TermsOfServiceUri": "http://example.com",
  "Version": 0,
  "Locked": true
}

Properties

Name	Type	Required	Restrictions	Description
Status	string	false	none	Is this software statement Active/Inactive
ClientId	string	false	none	Software Statement client Id
ClientName	string	false	none	Software Statement client name
Description	string	false	none	Software Statement description
Environment	string	false	none	The additional check for software statement, this field can avoid
OrganisationId	OrganisationId	false	none	Unique ID associated with the organisation
SoftwareStatementId	SoftwareStatementId	false	none	Unique Software Statement Id
Mode	string	false	none	Software Statement mode
RtsClientCreated	boolean	false	none	Client created flag
OnBehalfOf	string	false	none	A reference to fourth party organisation resource on the RTS Directory if the registering Org is acting on behalf of another
PolicyUri	string	false	none	The Software Statement policy compliant URI
ClientUri	string	false	none	The Software Statement client compliant URI
LogoUri	string(uri)	false	none	The Software Statement logo compliant URI
RedirectUri	[string]	false	none	The Software Statement redirect compliant URI
TermsOfServiceUri	string(uri)	false	none	The Software Statement terms of service compliant URI
Version	number	false	none	Software Statement version as provided by the organisation's PTC
Locked	boolean	false	none	Flag shows if assertion has been generated on the software statement - will be set to true when assertion is generated

Enumerated Values

Property	Value
Status	Active
Status	Inactive
Mode	Live
Mode	Test

SoftwareStatementRequest

{
  "ClientName": "string",
  "Description": "string",
  "OnBehalfOf": "string",
  "PolicyUri": "string",
  "ClientUri": "string",
  "LogoUri": "string",
  "Environment": "string",
  "Mode": "Live",
  "RedirectUri": [
    "string"
  ],
  "TermsOfServiceUri": "string",
  "Version": 1
}

Properties

Name	Type	Required	Restrictions	Description
ClientName	string	true	none	Software Statement client name
Description	string	false	none	Software Statement description
OnBehalfOf	string	false	none	A reference to fourth party organisation resource on the RTS Directory if the registering Org is acting on behalf of another
PolicyUri	string	true	none	The Software Statement compliant policy URI
ClientUri	string	true	none	The Software Statement compliant client URI
LogoUri	string	true	none	The Software Statement compliant logo URI
Environment	string	false	none	The additional check for software statement, this field can avoid environment checks.
Mode	string	false	none	The additional check to see if the environment reflected above is live or test.
RedirectUri	[string]	true	none	The Software Statement redirect URIs
TermsOfServiceUri	string	true	none	The Software Statement terms of service compliant URI
Version	number	true	none	Software Statement version as provided by the organisation's PTC

Enumerated Values

Property	Value
Mode	Live
Mode	Test

SoftwareStatementId

"string"

Unique Software Statement Id

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Unique Software Statement Id

SoftwareStatementAssertion

"string"

A signed JWT (JWS)

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	A signed JWT (JWS)

SoftwareAuthorityClaims

[
  {
    "SoftwareStatementId": "string",
    "SoftwareAuthorityClaimId": "string",
    "Status": "Active",
    "AuthorisationDomain": "string",
    "Role": "string"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[SoftwareAuthorityClaim]	false	none	none

SoftwareAuthorityClaim

{
  "SoftwareStatementId": "string",
  "SoftwareAuthorityClaimId": "string",
  "Status": "Active",
  "AuthorisationDomain": "string",
  "Role": "string"
}

Properties

Name	Type	Required	Restrictions	Description
SoftwareStatementId	SoftwareStatementId	false	none	Unique Software Statement Id
SoftwareAuthorityClaimId	SoftwareAuthorityClaimId	false	none	Unique ID associated with the authority claims for a software statement
Status	string	false	none	Is this authority claim Active/Inactive
AuthorisationDomain	string	false	none	Authorisation domain for the authority
Role	string	false	none	Roles for the Authority i.e. ASPSP, AISP, PISP, CBPII

Enumerated Values

Property	Value
Status	Active
Status	Inactive

SoftwareAuthorityClaimRequest

{
  "Status": "Active",
  "AuthorisationDomain": "string",
  "Role": "string"
}

Properties

Name	Type	Required	Restrictions	Description
Status	string	true	none	Is this authority claim Active/Inactive, default is active
AuthorisationDomain	string	true	none	Authorisation domain for the authority
Role	string	true	none	Roles for the Authority i.e. ASPSP, AISP, PISP, CBPII

Enumerated Values

Property	Value
Status	Active
Status	Inactive

SoftwareAuthorityClaimUpdateRequest

{
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
Status	string	true	none	This is used to set the status - Active/Inactive

Enumerated Values

Property	Value
Status	Active
Status	Inactive

ClientCreationRequest

{
  "id_token_signed_response_alg": "PS256",
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "string",
  "tls_client_auth_subject_dn": "string",
  "redirect_uris": [
    "string"
  ],
  "response_types": [
    "string"
  ],
  "grant_types": [
    "string"
  ],
  "scope": "string"
}

Properties

Name	Type	Required	Restrictions	Description
id_token_signed_response_alg	string	true	none	Signing algorithim that a client expects the server to return an id_token with. Must be PS256
token_endpoint_auth_method	string	true	none	Token endpoint authentication method
jwks_uri	string	true	none	Link to the application active jwks
tls_client_auth_subject_dn	string	false	none	The DN of the certificate that will be used to authenticate to this client
redirect_uris	[string]	true	none	redirect_uris uri must be provided. For client_credentials this should be an empty array.
response_types	[string]	true	none	response_types uri must be provided. For client_credentials this should be an empty array
grant_types	[string]	true	none	grant_types uri must be provided. For client_credentials this should be array containing ["client_credentials"]
scope	string	true	none	scopes to be tagged

Enumerated Values

Property	Value
id_token_signed_response_alg	PS256
token_endpoint_auth_method	private_key_jwt
token_endpoint_auth_method	tls_client_auth
token_endpoint_auth_method	client_secret_basic

ClientCreationResponse

{
  "application_type": "web",
  "tls_client_auth_subject_dn": "string",
  "grant_types": [
    "string"
  ],
  "id_token_signed_response_alg": "string",
  "require_auth_time": true,
  "subject_type": "string",
  "response_types": [
    "string"
  ],
  "post_logout_redirect_uris": [
    "string"
  ],
  "token_endpoint_auth_method": "string",
  "introspection_endpoint_auth_method": "string",
  "revocation_endpoint_auth_method": "string",
  "client_id_issued_at": 0,
  "client_id": "string",
  "jwks_uri": "string",
  "registration_client_uri": "string",
  "registration_access_token": "string",
  "redirect_uris": [
    "string"
  ],
  "request_uris": [
    "string"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
application_type	string	false	none	OIDC application type response
tls_client_auth_subject_dn	string	false	none	the subject dn used to authenticate this client
grant_types	[string]	false	none	grant_types
id_token_signed_response_alg	string	false	none	none
require_auth_time	boolean	false	none	none
subject_type	string	false	none	none
response_types	[string]	false	none	response_types
post_logout_redirect_uris	[string]	false	none	post_logout_redirect_uris
token_endpoint_auth_method	string	false	none	none
introspection_endpoint_auth_method	string	false	none	none
revocation_endpoint_auth_method	string	false	none	none
client_id_issued_at	number	false	none	none
client_id	string	false	none	none
jwks_uri	string	false	none	none
registration_client_uri	string	false	none	management uri location to manage client post creation
registration_access_token	string	false	none	token used to manage client post creation
redirect_uris	[string]	false	none	redirect_uris
request_uris	[string]	false	none	request_uris

Enumerated Values

Property	Value
application_type	web

AccessTokenRequest

{
  "grant_type": "client_credentials",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "assertion": "string"
}

Properties

Name	Type	Required	Restrictions	Description
grant_type	string	true	none	The Grant Type
client_assertion_type	string	true	none	Restrict to private_key_jwt
assertion	string	true	none	The assertion that is used to get a token

Enumerated Values

Property	Value
grant_type	client_credentials
client_assertion_type	urn:ietf:params:oauth:client-assertion-type:jwt-bearer

AccessTokenResponse

{
  "access_token": "string",
  "expires_in": 0,
  "token_type": "string",
  "scope": "string"
}

Properties

Name	Type	Required	Restrictions	Description
access_token	string	false	none	Access token
expires_in	integer	false	none	lifetime in seconds
token_type	string	false	none	none
scope	string	false	none	none

UserEmailId

"string"

User email address

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	User email address

SuperUserCreationRequest

{
  "Email": "string"
}

Properties

Name	Type	Required	Restrictions	Description
Email	string	true	none	The super user email address

SuperUsers

[
  {
    "Email": "string",
    "Status": "Active"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[SuperUser]	false	none	none

SuperUser

{
  "Email": "string",
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
Email	string	false	none	The super user email address
Status	string	false	none	Is this super user Active or Inactive

Enumerated Values

Property	Value
Status	Active
Status	Inactive

AuthorisationDomainName

"string"

Authorisation Domain Name

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Authorisation Domain Name

AuthorisationDomainRoleName

"string"

Authorisation Domain Role Name

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Authorisation Domain Role Name

AuthorityAuthorisationDomainId

"string"

Mapping ID between Authority and Authorisation Domain

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Mapping ID between Authority and Authorisation Domain

AuthorisationDomainUserCreateRequest

{
  "Email": "string",
  "AuthorisationDomainRole": "string",
  "ContactRole": "PTC"
}

Properties

Name	Type	Required	Restrictions	Description
Email	string	true	none	The user email address
AuthorisationDomainRole	string	true	none	The authorisation domain role for this user
ContactRole	ContactRoleEnum	true	none	The role of the contact

AuthorisationDomainUsers

[
  {
    "AuthorisationDomainUserId": "string",
    "Email": "string",
    "AuthorisationDomain": "string",
    "AuthorisationDomainRole": "string",
    "Status": "Active",
    "ContactRole": "PTC"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[AuthorisationDomainUser]	false	none	none

AuthorisationDomainUser

{
  "AuthorisationDomainUserId": "string",
  "Email": "string",
  "AuthorisationDomain": "string",
  "AuthorisationDomainRole": "string",
  "Status": "Active",
  "ContactRole": "PTC"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainUserId	string	false	none	Unique record ID
Email	string	false	none	The user email address
AuthorisationDomain	string	false	none	The authorisation domain for this user
AuthorisationDomainRole	string	false	none	The authorisation domain role for this user
Status	string	false	none	Is this user Active or Inactive
ContactRole	string	false	none	Type of role for this user

Enumerated Values

Property	Value
Status	Active
Status	Inactive
ContactRole	PTC
ContactRole	STC
ContactRole	PBC
ContactRole	SBC

AuthorisationDomainRequest

{
  "AuthorisationDomainName": "string",
  "AuthorisationDomainRegion": "string",
  "AuthorisationDomainDescription": "string"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	true	none	The authorisation domain name
AuthorisationDomainRegion	string	true	none	The authorisation domain region
AuthorisationDomainDescription	string	false	none	The authorisation domain description

AuthorisationDomains

[
  {
    "AuthorisationDomainName": "string",
    "AuthorisationDomainRegion": "string",
    "AuthorisationDomainDescription": "string",
    "Status": "Active"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[AuthorisationDomain]	false	none	none

AuthorisationDomain

{
  "AuthorisationDomainName": "string",
  "AuthorisationDomainRegion": "string",
  "AuthorisationDomainDescription": "string",
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	false	none	The authorisation domain name
AuthorisationDomainRegion	string	false	none	The authorisation domain region
AuthorisationDomainDescription	string	false	none	The authorisation domain description
Status	string	false	none	Is this Domain Active or Inactive

Enumerated Values

Property	Value
Status	Active
Status	Inactive

AuthorisationDomainRoleRequest

{
  "AuthorisationDomainName": "string",
  "AuthorisationDomainRoleName": "string",
  "AuthorisationDomainRoleDescription": "string"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	true	none	The authorisation domain name
AuthorisationDomainRoleName	string	true	none	The authorisation domain role name
AuthorisationDomainRoleDescription	string	false	none	The authorisation domain role description

AuthorisationDomainRoles

[
  {
    "AuthorisationDomainName": "string",
    "AuthorisationDomainRoleName": "string",
    "AuthorisationDomainRoleDescription": "string",
    "Status": "Active"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[AuthorisationDomainRole]	false	none	none

AuthorisationDomainRole

{
  "AuthorisationDomainName": "string",
  "AuthorisationDomainRoleName": "string",
  "AuthorisationDomainRoleDescription": "string",
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	false	none	The authorisation domain name
AuthorisationDomainRoleName	string	false	none	The authorisation domain role
AuthorisationDomainRoleDescription	string	false	none	The authorisation domain role description
Status	string	false	none	Is this mapping Active or Inactive

Enumerated Values

Property	Value
Status	Active
Status	Inactive

AuthorityAuthorisationDomainRequest

{
  "AuthorisationDomainName": "string"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	true	none	The authorisation domain name

AuthorityAuthorisationDomains

[
  {
    "AuthorisationDomainName": "string",
    "AuthorityId": "string",
    "AuthorityAuthorisationDomainId": "string",
    "Status": "Active"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[AuthorityAuthorisationDomain]	false	none	none

AuthorityAuthorisationDomain

{
  "AuthorisationDomainName": "string",
  "AuthorityId": "string",
  "AuthorityAuthorisationDomainId": "string",
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	false	none	The authorisation domain name
AuthorityId	string	false	none	The GUID of the Authority
AuthorityAuthorisationDomainId	string	false	none	The GUID of the Authority-Domain mapping
Status	string	false	none	Is this user Active or Inactive

Enumerated Values

Property	Value
Status	Active
Status	Inactive

OrganisationAuthorityDomainClaimId

"string"

Organisation Authority Domain Claim ID

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Organisation Authority Domain Claim ID

OrganisationAuthorityDomainClaimRequest

{
  "AuthorisationDomainName": "string",
  "AuthorityId": "string",
  "RegistrationId": "string"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	true	none	The authorisation domain name
AuthorityId	string	true	none	The Authority ID
RegistrationId	string	false	none	The registration ID

OrganisationAuthorityDomainClaims

[
  {
    "OrganisationAuthorityDomainClaimId": "string",
    "AuthorisationDomainName": "string",
    "AuthorityId": "string",
    "AuthorityName": "string",
    "RegistrationId": "string",
    "Status": "Active"
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[OrganisationAuthorityDomainClaim]	false	none	none

OrganisationAuthorityDomainClaim

{
  "OrganisationAuthorityDomainClaimId": "string",
  "AuthorisationDomainName": "string",
  "AuthorityId": "string",
  "AuthorityName": "string",
  "RegistrationId": "string",
  "Status": "Active"
}

Properties

Name	Type	Required	Restrictions	Description
OrganisationAuthorityDomainClaimId	string	false	none	The unique org authority domain claim ID
AuthorisationDomainName	string	false	none	The authorisation domain name
AuthorityId	string	false	none	The GUID of the Authority
AuthorityName	string	false	none	The name of the Authority
RegistrationId	string	false	none	The registration ID
Status	string	false	none	Is this user Active or Inactive

Enumerated Values

Property	Value
Status	Active
Status	Inactive

AuthorisationDomainUserId

"string"

Unique record ID to identify Domain user

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Unique record ID to identify Domain user

UserDetail

{
  "SuperUser": true,
  "SystemUser": true,
  "BasicInformation": {
    "UserEmail": "string",
    "Status": "Active"
  },
  "OrgAccessDetails": {
    "property1": {
      "OrgAdmin": true,
      "DomainRoleDetails": [
        {
          "AuthorisationDomainName": "string",
          "AuthorisationDomainRoleName": "string",
          "Status": "Active",
          "ContactRole": "PTC"
        }
      ]
    },
    "property2": {
      "OrgAdmin": true,
      "DomainRoleDetails": [
        {
          "AuthorisationDomainName": "string",
          "AuthorisationDomainRoleName": "string",
          "Status": "Active",
          "ContactRole": "PTC"
        }
      ]
    }
  },
  "DirectoryTermsAndConditionsDetails": {
    "RequiresSigning": true,
    "Updated": true,
    "TermsAndConditionsItem": {
      "TnCId": 0,
      "Version": 0,
      "Name": "string",
      "Type": "string",
      "Content": "string",
      "Status": "Active",
      "ExternalSigningService": {
        "ExternalSigningServiceName": "DocuSign",
        "ExternalSigningServiceSignerTemplateConfig": {
          "TemplateIdSigner1": "string",
          "TemplateIdSigner2": "string",
          "TemplateIdSigner3": "string",
          "TemplateIdSigner4": "string",
          "TemplateIdSigner5": "string",
          "TemplateIdSigner6": "string"
        },
        "ExternalSigningServiceSubject": "string"
      }
    }
  }
}

Properties

Name	Type	Required	Restrictions	Description
SuperUser	boolean	false	none	Is the user a super user
SystemUser	boolean	false	none	Is the user a system user
BasicInformation	object	false	none	none
» UserEmail	string	false	none	none
» Status	string	false	none	none
OrgAccessDetails	object	false	none	Map Key - Org ID, Map Value - Org Access Detail(contaning info about org admin and domain role details)
» additionalProperties	OrgAccessDetail	false	none	none
DirectoryTermsAndConditionsDetails	TermsAndConditionsDetails	false	none	Details of TnC

Enumerated Values

Property	Value
Status	Active
Status	Inactive

TermsAndConditionsDetails

{
  "RequiresSigning": true,
  "Updated": true,
  "TermsAndConditionsItem": {
    "TnCId": 0,
    "Version": 0,
    "Name": "string",
    "Type": "string",
    "Content": "string",
    "Status": "Active",
    "ExternalSigningService": {
      "ExternalSigningServiceName": "DocuSign",
      "ExternalSigningServiceSignerTemplateConfig": {
        "TemplateIdSigner1": "string",
        "TemplateIdSigner2": "string",
        "TemplateIdSigner3": "string",
        "TemplateIdSigner4": "string",
        "TemplateIdSigner5": "string",
        "TemplateIdSigner6": "string"
      },
      "ExternalSigningServiceSubject": "string"
    }
  }
}

Details of TnC

Properties

Name	Type	Required	Restrictions	Description
RequiresSigning	boolean	false	none	Does the Directory TnC require signing
Updated	boolean	false	none	Has the document updated since the user signed
TermsAndConditionsItem	TermsAndConditionsItem	false	none	none

UserCreateRequest

{
  "UserEmail": "string",
  "TermsAndConditionsId": 0
}

Properties

Name	Type	Required	Restrictions	Description
UserEmail	string	true	none	User's email
TermsAndConditionsId	integer	true	none	Id of the TnC(type = Directory), user has agreed to

UserOPInfo

{
  "sub": "string",
  "family_name": "string",
  "given_name": "string",
  "name": "string",
  "email": "string",
  "email_verified": true,
  "address": "string",
  "phone_number": "string",
  "phone_number_verified": true
}

The information contained within is subject to the scopes passed during token generation

Properties

Name	Type	Required	Restrictions	Description
sub	string	false	none	Contains the email address
family_name	string	false	none	Family name
given_name	string	false	none	Given name
name	string	false	none	Full name
email	string	false	none	Email address
email_verified	boolean	false	none	Is the email verified
address	string	false	none	Address
phone_number	string	false	none	Phone number
phone_number_verified	boolean	false	none	Is the phone number verified

WellKnown

{
  "acr_values_supported": [
    null
  ],
  "authorization_endpoint": "string",
  "claims_parameter_supported": true,
  "claims_supported": [
    null
  ],
  "code_challenge_methods_supported": [
    null
  ],
  "end_session_endpoint": "string",
  "check_session_endpoint": "string",
  "grant_types_supported": [
    null
  ],
  "id_token_signing_alg_values_supported": [
    null
  ],
  "issuer": "string",
  "jwks_uri": "string",
  "registration_endpoint": "string",
  "request_object_signing_alg_values_supported": "string",
  "request_parameter_supported": true,
  "request_uri_parameter_supported": true,
  "require_request_uri_registration": true,
  "pushed_authorization_request_endpoint": [
    null
  ],
  "response_modes_supported": [
    null
  ],
  "response_types_supported": [
    null
  ],
  "scopes_supported": [
    null
  ],
  "subject_types_supported": [
    null
  ],
  "token_endpoint_auth_methods_supported": [
    null
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    null
  ],
  "token_endpoint": "string",
  "userinfo_endpoint": "string",
  "userinfo_signing_alg_values_supported": [
    null
  ],
  "authorization_signing_alg_values_supported": [
    null
  ],
  "introspection_endpoint": "string",
  "introspection_endpoint_auth_methods_supported": [
    null
  ],
  "introspection_endpoint_auth_signing_alg_values_supported": [
    null
  ],
  "revocation_endpoint": "string",
  "revocation_endpoint_auth_methods_supported": [
    null
  ],
  "revocation_endpoint_auth_signing_alg_values_supported": [
    null
  ],
  "frontchannel_logout_supported": true,
  "frontchannel_logout_session_supported": true,
  "tls_client_certificate_bound_access_tokens": true,
  "claim_types_supported": [
    null
  ]
}

Properties

Name	Type	Required	Restrictions	Description
acr_values_supported	[any]	false	none	none
authorization_endpoint	string	false	none	REQUIRED. URL of the OP's OAuth 2.0 Authorization Endpoint
claims_parameter_supported	boolean	false	none	OPTIONAL. Boolean value specifying whether the OP supports use of the claims parameter, with true indicating support. If omitted, the default value is false
claims_supported	[any]	false	none	RECOMMENDED. JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for
code_challenge_methods_supported	[any]	false	none	none
end_session_endpoint	string	false	none	none
check_session_endpoint	string	false	none	none
grant_types_supported	[any]	false	none	OPTIONAL. JSON array containing a list of the OAuth 2.0 Grant Type values that this OP supports
id_token_signing_alg_values_supported	[any]	false	none	REQUIRED. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT
issuer	string	false	none	REQUIRED. URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier
jwks_uri	string	false	none	REQUIRED. URL of the OP's JSON Web Key Set [JWK] document.
registration_endpoint	string	false	none	RECOMMENDED. URL of the OP's Dynamic Client Registration Endpoint
request_object_signing_alg_values_supported	string	false	none	OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for Request Objects
request_parameter_supported	boolean	false	none	OPTIONAL. Boolean value specifying whether the OP supports use of the request parameter, with true indicating support. If omitted, the default value is false
request_uri_parameter_supported	boolean	false	none	OPTIONAL. Boolean value specifying whether the OP supports use of the request_uri parameter, with true indicating support. If omitted, the default value is true
require_request_uri_registration	boolean	false	none	OPTIONAL. Boolean value specifying whether the OP requires any request_uri values used to be pre-registered using the request_uris registration parameter
pushed_authorization_request_endpoint	[any]	false	none	none
response_modes_supported	[any]	false	none	OPTIONAL. JSON array containing a list of the OAuth 2.0 response_mode values that this OP supports
response_types_supported	[any]	false	none	REQUIRED. JSON array containing a list of the OAuth 2.0 response_type values that this OP supports
scopes_supported	[any]	false	none	RECOMMENDED. JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports
subject_types_supported	[any]	false	none	REQUIRED. JSON array containing a list of the Subject Identifier types that this OP supports
token_endpoint_auth_methods_supported	[any]	false	none	OPTIONAL. JSON array containing a list of Client Authentication methods supported by this Token Endpoint
token_endpoint_auth_signing_alg_values_supported	[any]	false	none	OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the Token Endpoint for the signature on the JWT
token_endpoint	string	false	none	URL of the OP's OAuth 2.0 Token Endpoint
userinfo_endpoint	string	false	none	RECOMMENDED. URL of the OP's UserInfo Endpoint
userinfo_signing_alg_values_supported	[any]	false	none	OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT
authorization_signing_alg_values_supported	[any]	false	none	none
introspection_endpoint	string	false	none	none
introspection_endpoint_auth_methods_supported	[any]	false	none	none
introspection_endpoint_auth_signing_alg_values_supported	[any]	false	none	none
revocation_endpoint	string	false	none	none
revocation_endpoint_auth_methods_supported	[any]	false	none	none
revocation_endpoint_auth_signing_alg_values_supported	[any]	false	none	none
frontchannel_logout_supported	boolean	false	none	none
frontchannel_logout_session_supported	boolean	false	none	none
tls_client_certificate_bound_access_tokens	boolean	false	none	none
claim_types_supported	[any]	false	none	OPTIONAL. JSON array containing a list of the Claim Types that the OpenID Provider supports

OrgAccessDetail

{
  "OrgAdmin": true,
  "DomainRoleDetails": [
    {
      "AuthorisationDomainName": "string",
      "AuthorisationDomainRoleName": "string",
      "Status": "Active",
      "ContactRole": "PTC"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
OrgAdmin	boolean	false	none	Is the user the org admin of the current org
DomainRoleDetails	[DomainRoleDetail]	false	none	Array of domain, role and status of domain role mapping

DomainRoleDetail

{
  "AuthorisationDomainName": "string",
  "AuthorisationDomainRoleName": "string",
  "Status": "Active",
  "ContactRole": "PTC"
}

Properties

Name	Type	Required	Restrictions	Description
AuthorisationDomainName	string	false	none	none
AuthorisationDomainRoleName	string	false	none	none
Status	StatusEnum	false	none	none
ContactRole	ContactRoleEnum	false	none	The role of the contact

TnCId

TnC unique identifier

Properties

Name	Type	Required	Restrictions	Description
anonymous	integer	false	none	TnC unique identifier

ClientId

"string"

The ClientID

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The ClientID

TermsAndConditionsPage

{
  "totalPages": 0,
  "totalSize": 0,
  "pageable": {
    "number": 0,
    "sort": {
      "sorted": true,
      "orderBy": [
        {
          "property": "createdAt",
          "direction": "ASC",
          "ignoreCase": true,
          "ascending": true
        }
      ]
    },
    "size": 0,
    "offset": 0,
    "sorted": true
  },
  "numberOfElements": 0,
  "size": 0,
  "content": [
    {
      "TnCId": 0,
      "Version": 0,
      "Name": "string",
      "Type": "string",
      "Content": "string",
      "Status": "Active",
      "ExternalSigningService": {
        "ExternalSigningServiceName": "DocuSign",
        "ExternalSigningServiceSignerTemplateConfig": {
          "TemplateIdSigner1": "string",
          "TemplateIdSigner2": "string",
          "TemplateIdSigner3": "string",
          "TemplateIdSigner4": "string",
          "TemplateIdSigner5": "string",
          "TemplateIdSigner6": "string"
        },
        "ExternalSigningServiceSubject": "string"
      }
    }
  ],
  "offset": 0,
  "empty": true,
  "pageNumber": 0
}

Properties

Name	Type	Required	Restrictions	Description
totalPages	integer	false	none	none
totalSize	integer	false	none	none
pageable	Pageable	false	none	none
numberOfElements	integer	false	none	none
size	integer	false	none	none
content	[TermsAndConditionsItem]	false	none	none
offset	integer	false	none	none
empty	boolean	false	none	none
pageNumber	integer	false	none	none

TermsAndConditionsItem

{
  "TnCId": 0,
  "Version": 0,
  "Name": "string",
  "Type": "string",
  "Content": "string",
  "Status": "Active",
  "ExternalSigningService": {
    "ExternalSigningServiceName": "DocuSign",
    "ExternalSigningServiceSignerTemplateConfig": {
      "TemplateIdSigner1": "string",
      "TemplateIdSigner2": "string",
      "TemplateIdSigner3": "string",
      "TemplateIdSigner4": "string",
      "TemplateIdSigner5": "string",
      "TemplateIdSigner6": "string"
    },
    "ExternalSigningServiceSubject": "string"
  }
}

Properties

Name	Type	Required	Restrictions	Description
TnCId	integer	false	none	Unique identifier for the Terms and Conditions Item
Version	integer	false	none	none
Name	string	false	none	none
Type	string	false	none	Identifies Participant or Directory
Content	string	false	none	Contains the MarkDown of the actual TnCs
Status	string	false	none	Is the TnC Active or Inactive
ExternalSigningService	object	false	none	none
» ExternalSigningServiceName	string	false	none	none
» ExternalSigningServiceSignerTemplateConfig	ExternalSigningServiceSignerTemplateConfig	false	none	none
» ExternalSigningServiceSubject	string	false	none	none

Enumerated Values

Property	Value
Status	Active
Status	Inactive
ExternalSigningServiceName	DocuSign

TermsAndConditionsCreateRequest

{
  "Type": "Participant",
  "Version": 0,
  "Name": "string",
  "Content": "string",
  "ExternalSigningServiceName": "DocuSign",
  "ExternalSigningServiceSignerTemplateConfig": {
    "TemplateIdSigner1": "string",
    "TemplateIdSigner2": "string",
    "TemplateIdSigner3": "string",
    "TemplateIdSigner4": "string",
    "TemplateIdSigner5": "string",
    "TemplateIdSigner6": "string"
  },
  "ExternalSigningServiceSubject": "string"
}

Properties

Name	Type	Required	Restrictions	Description
Type	string	true	none	Role for which this TnC applies
Version	integer	true	none	Version of the TnC document
Name	string	true	none	The Name of the TnC
Content	string	true	none	The MarkDown of the TnC
ExternalSigningServiceName	string	false	none	The Name of the External Signing Service
ExternalSigningServiceSignerTemplateConfig	ExternalSigningServiceSignerTemplateConfig	false	none	none
ExternalSigningServiceSubject	string	false	none	The Subject of the External Signing Service

Enumerated Values

Property	Value
Type	Participant
Type	Directory
ExternalSigningServiceName	DocuSign

ExternalSigningServiceSignerTemplateConfig

{
  "TemplateIdSigner1": "string",
  "TemplateIdSigner2": "string",
  "TemplateIdSigner3": "string",
  "TemplateIdSigner4": "string",
  "TemplateIdSigner5": "string",
  "TemplateIdSigner6": "string"
}

Properties

Name	Type	Required	Restrictions	Description
TemplateIdSigner1	string	false	none	Template ID for 1 signer
TemplateIdSigner2	string	false	none	Template ID for 2 signers
TemplateIdSigner3	string	false	none	Template ID for 3 signers
TemplateIdSigner4	string	false	none	Template ID for 4 signers
TemplateIdSigner5	string	false	none	Template ID for 5 signers
TemplateIdSigner6	string	false	none	Template ID for 6 signers

TermsAndConditionsUpdateRequest

{
  "Content": "string",
  "ExternalSigningServiceName": "DocuSign",
  "ExternalSigningServiceSignerTemplateConfig": {
    "TemplateIdSigner1": "string",
    "TemplateIdSigner2": "string",
    "TemplateIdSigner3": "string",
    "TemplateIdSigner4": "string",
    "TemplateIdSigner5": "string",
    "TemplateIdSigner6": "string"
  },
  "ExternalSigningServiceSubject": "string"
}

Properties

Name	Type	Required	Restrictions	Description
Content	string	true	none	The MarkDown of the TnC
ExternalSigningServiceName	string	false	none	The Name of the External Signing Service
ExternalSigningServiceSignerTemplateConfig	ExternalSigningServiceSignerTemplateConfig	false	none	none
ExternalSigningServiceSubject	string	false	none	The Subject of the External Signing Service

Enumerated Values

Property	Value
ExternalSigningServiceName	DocuSign

OrgAdminUserCreateRequest

{
  "UserEmail": "string"
}

Properties

Name	Type	Required	Restrictions	Description
UserEmail	string	true	none	Admin user email address

OrganisationAdminUsers

[
  {
    "Status": "Active",
    "UserEmail": "string",
    "DomainRoleDetails": [
      {
        "AuthorisationDomainName": "string",
        "AuthorisationDomainRoleName": "string",
        "Status": "Active",
        "ContactRole": "PTC"
      }
    ]
  }
]

Properties

Name	Type	Required	Restrictions	Description
anonymous	[OrganisationAdminUser]	false	none	none

OrganisationAdminUser

{
  "Status": "Active",
  "UserEmail": "string",
  "DomainRoleDetails": [
    {
      "AuthorisationDomainName": "string",
      "AuthorisationDomainRoleName": "string",
      "Status": "Active",
      "ContactRole": "PTC"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
Status	string	false	none	Is the admin user active
UserEmail	string	false	none	Users email address
DomainRoleDetails	[DomainRoleDetail]	false	none	none

Enumerated Values

Property	Value
Status	Active
Status	Inactive

ApiResources

{
  "totalPages": 0,
  "totalSize": 0,
  "pageable": {
    "number": 0,
    "sort": {
      "sorted": true,
      "orderBy": [
        {
          "property": "createdAt",
          "direction": "ASC",
          "ignoreCase": true,
          "ascending": true
        }
      ]
    },
    "size": 0,
    "offset": 0,
    "sorted": true
  },
  "numberOfElements": 0,
  "size": 0,
  "content": [
    {
      "ApiResourceId": "string",
      "ApiFamilyType": "string",
      "ApiVersion": 0,
      "ApiDiscoveryEndpoints": [
        {
          "ApiDiscoveryId": "string",
          "ApiEndpoint": "http://example.com"
        }
      ]
    }
  ],
  "offset": 0,
  "empty": true,
  "pageNumber": 0
}

Properties

Name	Type	Required	Restrictions	Description
totalPages	integer	false	none	none
totalSize	integer	false	none	none
pageable	Pageable	false	none	none
numberOfElements	integer	false	none	none
size	integer	false	none	none
content	[ApiResource]	false	none	none
offset	integer	false	none	none
empty	boolean	false	none	none
pageNumber	integer	false	none	none

ApiResource

{
  "ApiResourceId": "string",
  "ApiFamilyType": "string",
  "ApiVersion": 0,
  "ApiDiscoveryEndpoints": [
    {
      "ApiDiscoveryId": "string",
      "ApiEndpoint": "http://example.com"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
ApiResourceId	ApiResourceId	false	none	The unique ID of an Api version resource
ApiFamilyType	ApiFamilyType	false	none	The type of API this record describes
ApiVersion	number	false	none	The version number of the API
ApiDiscoveryEndpoints	[ApiDiscoveryEndpoint]	false	none	none

ApiResourceRequest

{
  "ApiFamilyType": "string",
  "ApiVersion": 0
}

Properties

Name	Type	Required	Restrictions	Description
ApiFamilyType	ApiFamilyType	false	none	The type of API this record describes
ApiVersion	number	false	none	The version number of the API

ApiFamilyType

"string"

The type of API this record describes

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The type of API this record describes

ApiResourceId

"string"

The unique ID of an Api version resource

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The unique ID of an Api version resource

ApiDiscoveryEndpoints

{
  "totalPages": 0,
  "totalSize": 0,
  "pageable": {
    "number": 0,
    "sort": {
      "sorted": true,
      "orderBy": [
        {
          "property": "createdAt",
          "direction": "ASC",
          "ignoreCase": true,
          "ascending": true
        }
      ]
    },
    "size": 0,
    "offset": 0,
    "sorted": true
  },
  "numberOfElements": 0,
  "size": 0,
  "content": [
    {
      "ApiDiscoveryId": "string",
      "ApiEndpoint": "http://example.com"
    }
  ],
  "offset": 0,
  "empty": true,
  "pageNumber": 0
}

Properties

Name	Type	Required	Restrictions	Description
totalPages	integer	false	none	none
totalSize	integer	false	none	none
pageable	Pageable	false	none	none
numberOfElements	integer	false	none	none
size	integer	false	none	none
content	[ApiDiscoveryEndpoint]	false	none	none
offset	integer	false	none	none
empty	boolean	false	none	none
pageNumber	integer	false	none	none

ApiDiscoveryEndpoint

{
  "ApiDiscoveryId": "string",
  "ApiEndpoint": "http://example.com"
}

Properties

Name	Type	Required	Restrictions	Description
ApiDiscoveryId	string	false	none	Unique Id of this discovery endpoint record
ApiEndpoint	string(uri)	false	none	A compliant URI

ApiDiscoveryEndpointRequest

{
  "ApiEndpoint": "http://example.com"
}

Properties

Name	Type	Required	Restrictions	Description
ApiEndpoint	string(uri)	false	none	A compliant URI

ApiDiscoveryEndpointId

"string"

The unique ID of an Api discovery endpoint resource

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	The unique ID of an Api discovery endpoint resource

OrgTermsAndConditionsPage

{
  "totalPages": 0,
  "totalSize": 0,
  "pageable": {
    "number": 0,
    "sort": {
      "sorted": true,
      "orderBy": [
        {
          "property": "createdAt",
          "direction": "ASC",
          "ignoreCase": true,
          "ascending": true
        }
      ]
    },
    "size": 0,
    "offset": 0,
    "sorted": true
  },
  "numberOfElements": 0,
  "size": 0,
  "content": [
    {
      "InitiatedBy": "string",
      "Role": "string",
      "TermsAndConditionsDetail": {
        "TermsAndConditionsItem": {
          "TnCId": 0,
          "Version": 0,
          "Name": "string",
          "Type": "string",
          "Content": "string",
          "Status": "Active",
          "ExternalSigningService": {
            "ExternalSigningServiceName": "DocuSign",
            "ExternalSigningServiceSignerTemplateConfig": {
              "TemplateIdSigner1": "string",
              "TemplateIdSigner2": "string",
              "TemplateIdSigner3": "string",
              "TemplateIdSigner4": "string",
              "TemplateIdSigner5": "string",
              "TemplateIdSigner6": "string"
            },
            "ExternalSigningServiceSubject": "string"
          }
        },
        "InititatedDate": "string",
        "ExternalSigningServiceEnvelopeId": "string",
        "ExternalSigningServiceEnvelopeStatus": "Completed",
        "ExternalSigningServiceEnvelopePasscode": "string"
      }
    }
  ],
  "offset": 0,
  "empty": true,
  "pageNumber": 0
}

Properties

Name	Type	Required	Restrictions	Description
totalPages	integer	false	none	none
totalSize	integer	false	none	none
pageable	Pageable	false	none	none
numberOfElements	integer	false	none	none
size	integer	false	none	none
content	[OrgTermsAnd