Page Comparison

...

• a User on your tenant with enough permissions to set up the authentication

  • permissions: edit_backend_settings and view_api_keys

  • this user is only used to make the setup calls, you must not use it as the base user for the API-Key!

• a dedicated User on your tenant who will be bound to your API-Key

• a Role (or more) to grant to the end user

  • Scoped to an inbox or to a (document, inbox) combination

import requests
from secrets import token_urlsafe
from getpass import getpass

tenant = "https://alfredo.contract-q.fit"

admin = "timothe@contract.fit"
password = getpass(f"User {admin} password: ")

sess = requests.Session()
res = requests.post(f"{tenant}/admin/auth", json={
    "username": admin,
    "password": password
})
res.raise_for_status()

jwt = res.json()["authentication_token"]
sess.headers = dict(Authorization=f"Bearer {jwt}")

...

res = sess.get(f"{tenant}/admin/inboxes")
res.raise_for_status()

inboxes = res.json()
invoice_inbox = next(filter(lambda x: x["name"] == "invoice", inboxes))

Create role

Use One time only: use / create a simple role with as little permissions as possible.

...

One time only: create the guest placeholder user. All end users using the API-Keys will be seen as this user.

The User must have equal or broader role and permissions than the API-Keys will require.

res = sess.post(f"{tenant}/admin/users", json={
    "username":"shared-link",
    "active": True,
    "password":token_urlsafe(18),  # The user password does not matter, use a randomly generated string
    "roles": [{"role": role["id"],"inbox": invoice_inbox["id"]}]
    })

res.raise_for_status()

user = res.json()

...

If you want to change the roles, just create a new API-Key and delete the old one.

To give access to a specific document you must also specify the inbox of the document within the same role definition; you can add multiple independent roles in the roles list, each one giving access to a single inbox or a (inbox, document) combination.

doc_id = "60ddb937b260064252bd5a98"  # your doc ID
roles = [
    {"role": role["id"], "inbox": invoice_inbox["id"]},
    {"role": role["id"], "document_id": doc_id},
     # same role as the user but limited to one doc
]

res = sess.post(f"{tenant}/admin/auth/api-key", json={
    "user": user["id"],
    "roles": roles
    })
res.raise_for_status()

token = res.json()["token"]

...