Documentation/Reference/Document API

Document API

Retrieve the documents shared by the user.

The private:doc.* scopes add claims to the id_token whose value is a URL. A simple GET on that URL, with the OIDC result access_token as bearer token, returns the document.

Request


Method	`GET`
URL	The URL given in the claim (for example `https://oidc-sandbox.a3bc.io/doc/id`)
Header	`Authorization: Bearer <access_token>`

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://oidc-sandbox.a3bc.io/doc/id

import base64, requests

r = requests.get(doc_url, headers={"Authorization": f"Bearer {access_token}"}, timeout=15)
r.raise_for_status()
body = r.json()
for d in body["document"]:
    open(d["name"], "wb").write(base64.b64decode(d["content"]))
print(body.get("metadata"))

Response

Status	Object	Comment
`200`	document	Document retrieved
`401`	error	Authentication failed
`500`	error	Internal server error

{
  "metadata": {
    "name": "passport",
    "identifier": "SPECI2014",
    "issued": "2014-04-05",
    "expired": "2024-04-04",
    "country": "nl",
    "issuedBy": "Burg van Stadt en Dorp"
  },
  "document": [
    { "name": "front.png", "content": "iVBORw0KGgoAAAANSUhEU..." },
    { "name": "back.png",  "content": "iVBORw0KGgoAAAANSUhEU..." }
  ]
}

document[].name: file name <name>.<extension> (png, jpg, jpeg or pdf).
document[].content: base64-encoded content.
metadata: information about the document itself (issuer, dates, type). Generally present for verified documents (private:doc.*).

The *.hash claims give the fingerprint (sha256:…) of each document, to check its integrity.

Error: {"code":"004013","message":"ingress auth: authentication failed"} (wrong token).

Metadata by scope

`private:doc.id`

Name	Type	Description
`name`	string	Type of id: `passport`, `resident permit` or `identity card`.
`identifier`	string	Unique id or serial number.
`issued`	date	Issue date.
`expired`	date	Expiration date.
`country`	string	Issuing country.
`issuedBy`	string	Official issuing organization.
`personalNumber`	string	Unique identifier of a foreigner (resident permit).
`remarks`	string	Free text zone of the resident permit.
`receiptIdentifier`	string	Identifier of a renewal receipt presented with an expired French resident permit.
`receiptIssued`	date	Receipt issue date (optional).
`receiptExpired`	date	Receipt expiration date (optional).

When receipt metadata is present, two documents are provided, in this order: the expired resident permit (PDF), then the receipt (png, jpeg, bmp or pdf).

`private:doc.address`, `private:doc.ssn`, `private:doc.bankaccount`

Not all information is always present, depending on the analyzed document.

Name	Type	Description
`name`	string	Type of proof document.
`author`	string	Issuer (usually the provider).
`issued`	date	Date of issuance.
`identifier`	string	Document reference.