This page describes the steps you need to take to integrate with the standard Duco Adaptive IDP API. This page serves as a tutorial.
This page describes the steps you need to take to integrate with the standard Duco Adaptive IDP API. This page serves as a tutorial. Connection through the API of Duco Adaptive IDP is possible via token authentication or mutual TLS certification. For technical details on how to implement it, see the Metamaze API documentation.
For this tutorial, we will use Postman to perform the API request.
API integration using token authentication
Step 1: Configure the input API and get a Bearer token
- Create (or refresh) a new Bearer token by clicking the two blue arrows
- Copy the Bearer token and store it for later use
- Click Save to store the generated Bearer token
Step 2: Find your organisationId and projectId
You can find the organisationId and projectId in the URL of e.g. the project settings:
Url parameters organisationId and projectId
Step 3: Base64 encode your document
To add documents to your JSON API request, you need to base64 encode them. In Linux and on Mac OS X, you can just run
> base64 <inputfile>
Tip: to immediately copy the base64 encoded file to your clipboard you can use
> base64 <inputfile> | pbcopy
Step 4: Create your request to start processing
In Postman, create a new request.
- Change the type from GET to POST
- Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process where {{organisationId}} and {{projectId}} are the values from Step 2.
- Under the Authorization tab, choose Bearer Token as the type. Fill in the generated Bearer Token from Step 1.
- Under Body, change the type to raw and select JSON as the body format.
- Add the following request body where you replace {{base64 encoded file}} with the output from Step 3. You can add optional metadata too
{
"files": [
{
"name": "mm-api-example.pdf",
"id": "mm-api-example",
"file": "{{base64 encoded file}}"
}
],
"metadata": {"example-key": "example-value"}
}
In Postman, you can click "Code" (top-right, under the Send and Save buttons) to quickly export your API call to the most popular programming languages immediately.
6. Click Send to send the request. You will receive a response like this with status code 200. Store the uploadId: you will need it to fetch the status and the results
Step 5: Create a new request to fetch the results
In Postman, create a new request.
- Set the request type as GET now.
- Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process/{{uploadId}} where {{organisationId}} and {{projectId}} are the values from Step 2, and {{uploadId}} is the ID you received in the response of Step 4.
- As above, add the Bearer Token authentication.
- Click Send to send the request and fetch the results.
- You will find the extracted values under documents[].aggregatedEntities.
Summary
In this tutorial, we showed the easiest way to integrate Duco Adaptive IDP. For other topics like receiving results immediately (push instead of pull), advanced authentication, restricting document types, uploading training data or adding metadata you can find information in the full API documentation.
Generating certificates for requests to Duco Adaptive IDP with mTLS
In the tutorial above, authentication was with a Bearer token. You might want to consider to add certificate-based authentication for an additional layer of security.
This guide provides step-by-step instructions on generating certificates using SSL for secure communication with Duco Adaptive IDP using mutual TLS (mTLS).
Step 1: Generating a key and a Certificate Signing Request (CSR)
To generate a key and a CSR, please follow the command given below:
openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=*.metamaze.eu'
Keep your client.key file private and protected.
Step 2: Send the CSR to Duco Support to sign with our CA
After generating a CSR, you can open a support ticket via support@du.co or the information provided on Getting support. In that support ticket, include the client.csr file as an attachment and ask to sign it.
After verifying your information, Duco Adaptive IDP will sign the CSR and provide you with a signed certificate.
For reference, we will use a command similar to:
Copy
openssl x509 -req -sha256 -days 365 -in client.csr -CA mm_ca.crt -CAkey mm_ca.key -set_serial 02 -out client.crt
Step 3: Add the certificate content to Duco Adaptive IDP
After generating the client.crt file, you can paste the content of it in the Duco Adaptive IDP project settings > Input > REST API. The certificate should have the following structure:
---BEGIN CERTIFICATE---
...
---END CERTIFICATE---
Step 4: Test API calls in Postman
To configure Postman correctly with mTLS, follow these steps:
In Postman, navigate to Settings > Certificates and click "Add Certificate"
Enter the following information
- Add HOST *.metamaze.eu
- Add CRT file client.crt that was provided by Duco
- Add your KEY file client.key
- Leave PFX file empty
- (Optional) If you set a passphrase when generating the key, add the passphrase here too.
Postman automatically looks at the hostname of every API call to decide if client authentication is needed. By adding the host *.metamaze.eu, all API calls will be covered.
For testing purposes, we provide an endpoint at app.metamaze.eu/test-sslthat you can use. When sending a POST request to that endpoint with an empty body, you should receive a response similar to
Fingerprint: [the sha1 fingerprint of certificate]
Verified: SUCCESS
Subject: CN=*.metamaze.eu
Overview of files
At the end of the process, you will have the following files:
- client.csr (not needed anymore, it was used for step 2 only)
- client.key (use this to sign the request to Duco Adaptive IDP , keep this private)
- client.crt (used to validate the request in Duco Adaptive IDP , to be pasted in the project settings.)
Please note that both the client.key and client.crt files are necessary for secure communication with Duco Adaptive IDP and should be kept securely.
Note that self-signed certificates are not supported. Certificates for client authentication using mTLS must be signed by the Duco Certificate Authority.