Key Exchange
1. Signed Request
All requests to our APIs must use the HTTPS protocol with TLS 1.2 or 1.3, and must carry two headers:
- API-CLIENT-KEY: A key provided by our Integration team that identifies a specific integration;
- AUTHORIZATION: A signature of the request, generated as explained in this manual;
By default, QI CTVM uses the asymmetric key standard, in which there are two different keys: one for signing, called the private key, and one for reading, called the public key. With the private key, the integrating partner must sign the request following the JWT standard. The integrating partner is responsible for generating the key pair and providing the public key to QI CTVM so that we can validate their requests.
The private key is for the integrating partner's exclusive use and must be stored securely. QI CTVM will never, under any circumstances, ask you to share it with us.
2. How to deliver the public key
If you are a manager or a consultant, the recommended path is to register the public key yourself, through the Manager Portal or Consultant Portal screen. See the complete guide in Portal Integration.
Through the portal you create the integration, register the public key and receive the API Key on the screen itself — no key travels by email. Registration is immediate, the key fingerprint is visible for checking, and rotation can be done at any time without opening a ticket. This is the standard procedure in both Sandbox and Production.
To get started, send the integration team the name, email and CPF of the master user responsible for the homologation — and nothing else. The public key must not be attached to that request.
The remaining access profiles — assignors, originators, investors and distributors — still send the generated public key to the QI Tech integration team, at integracao.dtvm@qitech.com.br, and wait for the integration to be configured.
3. Generating the pair
You can generate the key pair in the portal itself, at registration time — the private key is generated in your browser and downloaded only to you (see Portal Integration) — or generate it locally in your terminal.
To generate a private key on a UNIX machine, run:
$ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key
Then, from this private key, generate your public key.
$ openssl ec -in private.key -pubout -outform PEM -out public.key.pub
The public key is the public.key.pub file. That file — and only that file — is what should be registered in the portal or sent to the integration team.