Sending Encoded Requests

All Truora API endpoints can receive a signed JSON Web Token (JWT) as the content of the request. This section will explain how to use this feature to protect data sent in your requests to our API.

Why send a signed JWT in the request body?

The information you send in the JWT can be verified and trusted because it is digitally signed using public/private key pairs. Therefore, we can ensure that only the party that owns the private key is the one that signed it, and verify the integrity of the claims contained within the JWT.

You can read more about the JWT standard here.

How to send encoded and signed requests?

Let's say you want to create a Background Check (check out the Checks API reference here).

1. First, you need to have a private and public key.

Let's say this is your private key,

-----BEGIN PRIVATE KEY----- MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQC7VJTUt9Us8cKj MzEfYyjiWA4R4/M2bS1GB4t7NXp98C3SC6dVMvDuictGeurT8jNbvJZHtCSuYEvu NMoSfm76oqFvAp8Gy0iz5sxjZmSnXyCdPEovGhLa0VzMaQ8s+CLOyS56YyCFGeJZ qgtzJ6GR3eqoYSW9b9UMvkBpZODSctWSNGj3P7jRFDO5VoTwCQAWbFnOjDfH5Ulg p2PKSQnSJP3AJLQNFNe7br1XbrhV//eO+t51mIpGSDCUv3E0DDFcWDTH9cXDTTlR ZVEiR2BwpZOOkE/Z0/BVnhZYL71oZV34bKfWjQIt6V/isSMahdsAASACp4ZTGtwi VuNd9tybAgMBAAECggEBAKTmjaS6tkK8BlPXClTQ2vpz/N6uxDeS35mXpqasqskV laAidgg/sWqpjXDbXr93otIMLlWsM+X0CqMDgSXKejLS2jx4GDjI1ZTXg++0AMJ8 sJ74pWzVDOfmCEQ/7wXs3+cbnXhKriO8Z036q92Qc1+N87SI38nkGa0ABH9CN83H mQqt4fB7UdHzuIRe/me2PGhIq5ZBzj6h3BpoPGzEP+x3l9YmK8t/1cN0pqI+dQwY dgfGjackLu/2qH80MCF7IyQaseZUOJyKrCLtSD/Iixv/hzDEUPfOCjFDgTpzf3cw ta8+oE4wHCo1iI1/4TlPkwmXx4qSXtmw4aQPz7IDQvECgYEA8KNThCO2gsC2I9PQ DM/8Cw0O983WCDY+oi+7JPiNAJwv5DYBqEZB1QYdj06YD16XlC/HAZMsMku1na2T N0driwenQQWzoev3g2S7gRDoS/FCJSI3jJ+kjgtaA7Qmzlgk1TxODN+G1H91HW7t 0l7VnL27IWyYo2qRRK3jzxqUiPUCgYEAx0oQs2reBQGMVZnApD1jeq7n4MvNLcPv t8b/eU9iUv6Y4Mj0Suo/AU8lYZXm8ubbqAlwz2VSVunD2tOplHyMUrtCtObAfVDU AhCndKaA9gApgfb3xw1IKbuQ1u4IF1FJl3VtumfQn//LiH1B3rXhcdyo3/vIttEk 48RakUKClU8CgYEAzV7W3COOlDDcQd935DdtKBFRAPRPAlspQUnzMi5eSHMD/ISL DY5IiQHbIH83D4bvXq0X7qQoSBSNP7Dvv3HYuqMhf0DaegrlBuJllFVVq9qPVRnK xt1Il2HgxOBvbhOT+9in1BzA+YJ99UzC85O0Qz06A+CmtHEy4aZ2kj5hHjECgYEA mNS4+A8Fkss8Js1RieK2LniBxMgmYml3pfVLKGnzmng7H2+cwPLhPIzIuwytXywh 2bzbsYEfYx3EoEVgMEpPhoarQnYPukrJO4gwE2o5Te6T5mJSZGlQJQj9q4ZB2Dfz et6INsK0oG8XVGXSpQvQh3RUYekCZQkBBFcpqWpbIEsCgYAnM3DQf3FJoSnXaMhr VBIovic5l0xFkEHskAjFTevO86Fsz1C2aSeRKSqGFoOQ0tmJzBEs1R6KqnHInicD TQrKhArgLXX4v3CddjfTRJkFWDbE/CkvKZNOrcf1nhaGCPspRJj2KUkj1Fhl9Cnc dn/RsYEONbwQSjIfMPkvxF+8HQ== -----END PRIVATE KEY-----

and this is your public key

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1SU1LfVLPHCozMxH2Mo 4lgOEePzNm0tRgeLezV6ffAt0gunVTLw7onLRnrq0/IzW7yWR7QkrmBL7jTKEn5u +qKhbwKfBstIs+bMY2Zkp18gnTxKLxoS2tFczGkPLPgizskuemMghRniWaoLcyeh kd3qqGElvW/VDL5AaWTg0nLVkjRo9z+40RQzuVaE8AkAFmxZzow3x+VJYKdjykkJ 0iT9wCS0DRTXu269V264Vf/3jvredZiKRkgwlL9xNAwxXFg0x/XFw005UWVRIkdg cKWTjpBP2dPwVZ4WWC+9aGVd+Gyn1o0CLelf4rEjGoXbAAEgAqeGUxrcIlbjXfbc mwIDAQAB -----END PUBLIC KEY-----

1. Now, you have to share your public key with Truora using the following API https://docs.accounts.truora.com/#post-/v1/account/tenant/jwt. If you have already done this step, you do not have to repeat it.

2. After setting up your public key in your Truora account, you need to generate a JWT token and sign it with your Private Key. You can do it in the https://jwt.io/ website by using the following steps:

3. Select the algorithm RS256 from the Algorithm drop-down menu. Currently we only support the RS256 algorithm to sign the JWT.

4. Enter the header and the request payload. For this example we are going to use the following header and payload

   Header: { "alg": "RS256", "typ": "JWT" } Payload: { "country": "MX", "type": "person", "user_authorized": true, "national_id": "MUTT920802MDFXLR04", "iss": <the name of your Truora account>, "aud": "ValidacionIdentidad", "sub": "1234567890", "iat": 1516239022 } 3. Enter you private key in the Private Key field and enter you Public key in the Public Key field of the Verify Signature section.

A token is generated in the Encoded section. Copy this token on your system for further use.

1. Now you are ready to send the request.

2. For this example, create a POST request to the Create Check endpoint. https://api.checks.truora.com/v1/checks

3. Create a Header named Truora-API-Key and set its value to your Truora API Key (if you don't have one, check out our getting started section).
4. Create a Header named Content-Type and set its value to application/jwt.
5. Set the Body to the JWT token generated in the previous step in the text/plain format. The JWT token will be something like this eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb3VudHJ5IjoiTVgiLCJ0eXBlIjoicGVyc29uIiwidXNlcl9hdXRob3JpemVkIjp0cnVlLCJuYXRpb25hbF9pZCI6Ik1VVFQ5MjA4MDJNREZYTFIwNCIsImlzcyI6InRydW9yYXRlYW1zdGFnaW5nIiwiYXVkIjoiVmFsaWRhY2lvbklkZW50aWRhZCIsInN1YiI6IjEyMzQ1Njc4OTAiLCJpYXQiOjE1MTYyMzkwMjJ9.QbckwY-O34PdHMgfRcyV8j7cG78NmEATzZLhwyEuWb3D1q5fky2UWEJLkjSm3bJsnXcZmIDKd5VVDEixFQjSb6JdIJHrU1t5T9cdJ9GIELJKR8j-RPK9MSxTYZ_jXqfFmwsERDxoLWL0sm3c2ailq-ICVRokinyi7bUn9jaNwF5NqjhwKK3rOYBokNHbJaCNyzT5CeC3X2a1KK-RxwfXJUBjzyI0lkSmB740T87yx-gzi57KTqgt4cUujtSuTegvq2GZfmrVruYJJ-iTesYNdGkIdQQFjyTfJjTmlWa9QMc5JqM8AAT2LnVHFCXXvxQsECeq_FlGN0b721WCVD_a1Q
6. Send the request.

What if I change my public key?

After changing your Public key in your Truora Account, the previous key will be available for 5 minutes. For the first 5 minutes you'll be able to send requests signed with any of the two Public keys.

After 5 minutes, the old Public key is permanently deleted from you account and only requests signed with the new key will be accepted. You have to wait for the 5 minutes to pass to update the Public Key again.