View source for Choosing an Authentication Strategy

== Updox API Authentication Schemes ==

Updox API authentication comes in two "flavors": "Application Authentication" and "Individual Authentication". In both types, every API includes a common authentication header. This header contains 6 fields; 4 are used to employ Application Authentication, two are used for Individual Authentication. These methods can be mixed and matched on an API-by-API basis, but certain APIs can only be called using Application Authentication (PracticeCreate/Update/Save, for example).

=== Application Authentication ===

Application Authentication is most useful when APIs are being called from a server, or other controlled platform. By employing Application Authentication, ID and password maintenance is greatly simplified, in fact, it is largely eliminated. Your entire application is granted a single ID and password. In the authentication header, these are called applicationId and applicationPassword. By using this app-level ID and password, your application is "trusted" to freely operate on your accounts by further specifying an accountId and a userId in the authentication header. Neither the accountId nor the userId are Updox values, rather they are your system's key values for a group (practice, clinic, etc.) and individual (provider, user, etc.), respectively. This is different than many APIs, but it allows you to work with your data, and reference your users on your terms, without requiring you create places to store Updox key values. 

Sample JSON for PingWithAuth:
    {
        "auth": {
            "applicationId": "updox",
            "applicationPassword": "tmo>gQsnTwf,ArM{GPC]u[+yFf9d]B%:dt92V4Ctjk]raKZQZp",
            "accountId": "2001002",
            "userId": "1337"
        } 
    }

=== Individual Authentication ===

Individual Authentication is very straightforward: each account defined in Updox has an ID and password. This ID and password is passed in the authentication header as loginId and loginPassword. By passing loginId and loginPassword in the API authentication header, you specify the user's credentials in Updox terms. This is often preferable when APIs are called from software that is installed on your customers' premises, as no shared authentication credentials need to be stored.

Sample JSON for PingWithAuth:
    {
        "auth": {
            "loginId": "updoxuser",
            "loginPassword": "a2@::6$>8{6.#@H"
        }
    }

== Updox Direct Messaging SMTP Edge Protocol Authentication ==

We provide two layers of authentication:
* The first is a Mutual TLS connection where both client and server certificates are validated against trusted Certificate Authorities.
* The second is Basic auth where the provided username and password must be valid for the account that owns the sender address.


== Updox Direct Messaging XDR Edge Protocol Authentication ==
* The endpoint requires a client certificate, which we map to a given practice using information embedded in the certificate. 
* From there we validate that the sender's address is bound to that practice.