API Key Generation & Authentication

How to request and provide authentication for use with the Notarize API.

Notarize uses API keys to provide access to its APIs. API keys are distributed per organization, and consist of 24-character unique tokens, with associated settings on a given API key.

How do I use an API key?

When pinging any endpoint in the Notarize API API Endpoint Reference, you must include an API key in your request.

Include your API key as the ApiKey header. This is case-sensitive!

Here's an example, using cURL.

curl https://api.notarize.com/v1/transactions \
  -H "ApiKey: test_key_1234"

How do I manage and request API keys?

Visit the Integrations page of your business account (https://business.notarize.com/settings/api). From here you can view all currently existing API keys and their details, revoke keys, or manage the settings of your API keys.

What are the various API key settings and how are they managed?

Access Level

The most important API key setting will be its access level. This is set on a key-by-key basis when the key is created, and cannot be modified after creation.

There are currently two access levels:

  • full: An API key with full access can perform any and all CRUD actions described in the API reference. You should consider this key secret, and only expose it for internal code usage.
  • client_only: An API key with client_only access can only create transactions. (That is, it can only access the /transaction `POST endpoint). This key is intended for usage in client-based applications, and thus can be freely exposed. A common use will be in EasyLink applications.


Use the correct API key!

We mean it: make sure you expose the right API key for your application. Once a key is leaked, you can revoke it, but there's no way to undo any damage someone might have been able to perform in between.

Misc Settings And Locking Values

There are a number of other miscellaneous settings that can be set directly on the API key as a security measure, to prevent misuse if the API is intentionally (or unintentionally) exposed.

Where applicable, you can lock the value of the setting to indicate that anyone who uses API key must adhere to that value. That is, even if the key user applies another setting when they ping the API, the Notarize API will detect a mismatch and report an error.

Less strictly, you can also simply set a default value, but leave the value unlocked. If an API key user provides a contrasting value, it will override the default, but apply the default otherwise.


Check the defaults for the defaults!

All API keys will come with a suite of default values when first created. Furthermore, client_only API keys will have locked defaults when first created. These values are selected as both a convenience and security measure, but you may find that they don't suit your initial needs.


After access_level, the most important API key setting will probably be the payer. This represents who will be responsible for paying for a completed transaction, and is set directly on the API key as a security measure. Possible values include the customer and the organization. It's set to customer by default.


There are a number of whitelists that you can apply to your API key.

  • Document URL: You can whitelist what document URLs will be permitted for use in transactions.
  • Referrer URL: You can whitelist the possible referrer URLs that EasyLink will redirect users back to after they complete a transaction.

All whitelists consist of a group of regular expressions matching on whole URLs, which you can add to and remove from. Included in the API key settings is a tool to test your whitelist against a URL to see whether it's valid or invalid.

By default, no whitelists are set, meaning that all document and referrer URLs will be permitted.


Self-serve whitelist setting is currently not supported, though you can have Support manually enabled whitelists. Please stay tuned as the feature is fine-tuned and released. Please contact Support if you have any questions.

Transaction Creation Settings

There are a number of other miscellaneous settings that correspond to the various parameters you can apply to any given transaction when using the /transaction POST endpoint. As many as are applicable are included in your API key settings, and can be individually tuned. Please refer to the API reference Create a transaction for full details on what each parameter does.

Support / Security

If you're having issues, or need clarification regarding your API keys, please contact Support.

Similarly, if you suspect you've had an API key leakage, immediately revoke the key, then contact Support for help investigating the scope of the leakage and what malicious actions might have been taken using the key.