Home - dgt30-eng/General GitHub Wiki

The documentation for this API provides a detailed description of the available endpoints with examples of the responses obtained, as well as information

about their usage.

Some prior considerations to take into account are:

  • The API uses JSON Web Tokens for authentication.

  • API requests must be made with GET o POST requests as appropriate.

  • All responses that are not returned with an HTTP 200

    code can be considered an error.

  • All responses are returned in JSON format.

Version

The versioning of the API is determined in the URL itself. For example, for

version 1 we will get the following URL:

{baseUrl}/v1/xxx....

Authentication

  • To identify clients, the platform uses a system based on X509 Digital Certificates. This must be requested via email [email protected]. A form will be sent from the platform to fill in the identification of the owner of the certificate as well as the IP addresses from which the client will connect to the platform. For security, access from them will only be allowed using the certificate granted in each connection.

  • As a previous step to obtaining the token, you must have the security

    certificate and that the IP is on the allowed list.

  • The cn that is contained in the certificate that is used is the one that the application uses to check if it exists in the user registry.

{baseUrl}/v1/token

  • If the authentication is valid, a response is obtained with the date and time in UTC format when it was generated, when it expires and the token itself.

    {
    "issuedAt": "2021-04-01T09:09:16.284Z",
    "expiration": "2021-04-02T09:09:16.284Z",
    "token": "Bearer eyJhbGciOiJIUzUxMiJ9.e......."
}

  • Also, if a request is made with an expired token, an HTTP 400 – Bad Request error is received with the response as in the following example. A new token must be requested to continue making requests to the API.

    {
    "status": 400,
    "code": 6,
    "message": "Expired token received"
}

  • To make requests to the API endpoints, an attribute must be attached to the request headers in the header (Authorization) and its value will be Bearer (the type of token obtained) plus the value of the token that you have obtained separated by a space. For example:

    Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJDTW9iaWxpdHkzLjAiLCJzdWIiOiJwcnVlYmEiLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwiaWF0IoxNjE2NDIxMDYyLCJleHAiOjE2MTY0MjQ2NjJ9.N8KimN9_IgtjXX2Wv-rXLKK929mavlkaakxY_NzHVFgN9DWT8bqRVeTaBgL5GbzDfZSPZXDutoVwjdbTEx3FbA
    2021-03-24-13-21-32-image.png

Digital Certificates

The certificates generated are automatically sent by DGT3.0 platform to the email address indicated in the form, via two emails: one contains a .zip file with the certificates and the other contains the passphrase (password) to unzip the package and to be used with the .pfx certificate (in case of using this type of certificate).

In case you don't receive these emails, you should:

  • Check your email's Spam folder
  • Have your IT team check if your email server has blocked the reception of these emails. This can happen because it's an email generated and sent automatically by the platform, which includes the digital certificates as attachments, which sometimes is considered a dangerous reception. In such a case, the appropiate exceptions should be included to receive all emails from [email protected]

Certificate Renewal Automation

The certificates provided by the DGT3.0 platform are valid for one year.

  • Two months before their expiration, you will receive an automatic email notifying you of the upcoming date
  • One month before this date, you will receive an automatic email with the renewed certificates

It's important that you check the reception of these emails and, if necessary, make the appropiate changes to receive them, as they are designed to help keep the certificates always valid and prevent them from expiring due for forgetting this date.

MQTT

The information related to the MQTT broker is available here.

⚠️ **GitHub.com Fallback** ⚠️