Best practices and troubleshooting a claims source server

Below are some guidelines to run an external claims source API server.

Access and protocol  

The claims source must be accessible from the internet via HTTPS.  

e.g. https://example.com  

Endpoint and method  

The claims source must expose an endpoint supporting a HTTPS request using the “GET” method. This endpoint is what MATTR VII will call when querying the claims source.  

e.g. HTTP GET -> https://example.com/myclaims  

Response  

The MATTR VII claims source integration expects the HTTP response from the claims source to conform to the following rules :

• Return a 2XX HTTP status code when the request was successful.  

• The response body of the request is valid JSON, denoted by the application/json MIME type.  

• The JSON returned must be a JSON object, where each key in the object is a claim name and each value is a claim value.  

• If no claims are found, an empty object should be returned in the response body.

• Ensure the response is within three seconds to avoid MATTR VII request timeout .

• Only respond with error codes when something exceptional happens.

MATTR VII will log the error, but it will not immediately affect issuance. It will be processed in the same manner as returning an empty response. Issuance will only fail when it does not meet the requirements of the credential type being issued, e.g., if no value for a mandatory claim could be found.