Skip to main content

Introduzione

Autenticazione​

Tutte le chiamate esposte dalle API richiedono una autenticazione basata su OAUTH2. Occorre quindi che venga fornita una coppia di client id e client secret da usare per richiedere tale token.

Stacco token​

Una volta entrati in possesso della coppia di credenziali(clientId e clientSecret), si deve effettuare la seguente chiamata:

curl --location '$url' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id='$clientId' \
--data-urlencode 'client_secret=$clientSecret' \
--data-urlencode 'scope=CertificationAuthority_API'

Dove url varrà

La response, in caso di status code 200, conterrà nel field access_token il token da usare di seguito

{
    "access_token": "$accessToken",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "CertificationAuthority_API"
}

la durata del token è tipicamente 1 ora ed è riportata nel field expires_in

Chiamate API​

Ottenuto il token, tutte le chiamate successive dovranno contenere quest'ultimo nel header authentiication in qualità di bearer token:

"Authorization": "Bearer $accessToken"

Tracciamento chiamata​

Ogni response contiente l'header x-fnext-id contenente un id che permette di ricostruire il flusso delle chiamate in CA. In caso di errore x-fnext-id == response.traceId

Errori​

In caso di errore, le chiamate all'API ritornano:

  • se 401 o 403 il body della response non è presente, è presente un header www-authenticate che include le informazioni
  • negli altri casi il body conterrà la struttura
{
    "title": "$title", //tipo di errore
    "status": "$status", //status delle errore 4xx/5xx
    "detail": "$detail", //dettagli dell'errore
    "traceId": "$traceId", //traceId da comunicare per il troubleshooting
    "code": "$code", //codice di errore
    "instance": "$instance" //path invocata
    "type": "$type" //pagina di documentazione
    "errors": { //eventuali errori su validazione dell'input
        
    }
}
Esempio

{
    "type": "https://ca-test.teamsystem.cloud/api/v1/ca-registry/values/errors",
    "title": "Bad Request",
    "status": 400,
    "detail": "Request body validation error",
    "instance": "/api/v1/certificate",
    "traceId": "65f0a0be559a318b5d6280057b6d2074",
    "code": "GNR_001",
    "errors": {
        "profiles": "'AUTO,SEAL1' is not of a required type"
    }
}

Importante in particolar modo il traceId che deve essere comunicato nei ticket di assistenza per facilitare il troubleshooting.