Page last updated: October 29, 2026
OAuth 2.0 Authentication
Every API endpoint accepts either of two forms of authentication:
- HTTP Basic Authentication with your API ID and API key on every request, as shown in the rest of this documentation.
- OAuth 2.0 Bearer tokens, using the client credentials grant.
With OAuth 2.0, you exchange your API ID and API key for a short-lived access token, then send that token on every other request. Your API ID is your OAuth client_id, and your API key is your OAuth client_secret, which you can find on your API credentials page.
By default, HTTP Basic Authentication keeps working alongside OAuth 2.0. If you would like your organization to require OAuth 2.0, please reach out to us at support@notarylive.com. Once it is required, your API ID and API key are only accepted by the token and revoke endpoints. Every other endpoint returns a 401 response when called with HTTP Basic Authentication:
{
"success": 0,
"errors": [
{
"code": "oauth_required",
"message": "Your organization requires OAuth 2.0. Request an access token from POST /api/oauth/token and send it in the Authorization header as a Bearer token."
}
]
}
The requirement applies to all of your organization's credentials, including sandbox credentials, so you can test the full flow in the sandbox environment.
Step 1: Request an Access Token
Send a POST request to the token endpoint with grant_type=client_credentials in an application/x-www-form-urlencoded body, and authenticate with HTTP Basic Authentication:
curl -X POST "https://notarylive.com/api/oauth/token" \
-u '((your_api_id)):((your_api_key))' \
-d 'grant_type=client_credentials'
If your OAuth library sends the client credentials in the request body instead, that is also accepted:
curl -X POST "https://notarylive.com/api/oauth/token" \
-d 'grant_type=client_credentials' \
-d 'client_id=((your_api_id))' \
-d 'client_secret=((your_api_key))'
A successful request returns:
{
"access_token": "8f14e45fceea167a5a36dedd4bea2543b8e3fdc92e2b5f3f6ac0a0b1d8c7e4f2",
"token_type": "Bearer",
"expires_in": 3600
}
| Field | Description |
access_token |
The token to send on your API requests. Store it securely. |
token_type |
Always Bearer. |
expires_in |
The number of seconds until the token expires. |
Access tokens expire 60 minutes after they are issued.
Step 2: Use the Access Token
Send the token in the Authorization header in place of your API ID and API key. Everything else about the request stays the same. For example, creating a RON session order:
curl -X POST "https://notarylive.com/api/v3/order/create" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ((access_token))' \
-d $'{"internal_id": "((internal_order_id))", "participants": [{"email": "john.doe@notarylive.com", "last_name": "Doe", "type": "signer", "first_name": "John"}]}'
Revoking an Access Token
If you no longer need an access token, or believe one has been exposed, you can revoke it before it expires. Authenticate the same way you do at the token endpoint, and send the token in an application/x-www-form-urlencoded body:
curl -X POST "https://notarylive.com/api/oauth/revoke" \
-u '((your_api_id)):((your_api_key))' \
-d 'token=((access_token))'
A successful request returns a 200 response with an empty body, and the token stops working immediately. Following the OAuth 2.0 token revocation standard, the response is also a 200 when the token is unknown, has already expired, or was issued to different credentials. Tokens issued to other credentials are never revoked.
Revoking a token does not cancel any orders already created with it. Those orders continue as normal. Revoking a token also does not affect your API ID and API key. If you believe your API key itself has been exposed, delete the credential from your API credentials page and create a new one instead. That invalidates every token issued for it.
Errors use the same format and codes as the token endpoint. A missing token parameter returns invalid_request.
Token Endpoint Errors
Errors from the token endpoint follow the OAuth 2.0 error format, which is different from the format used by our other endpoints:
{
"error": "invalid_client",
"error_description": "Client authentication failed."
}
| HTTP status | error | Description |
| 400 | invalid_request |
The grant_type parameter is missing or empty, a parameter was sent with an invalid value type, or the client credentials were sent both in the Authorization header and in the body. |
| 401 | invalid_client |
The API ID and API key are wrong, have been deleted, or belong to an organization that does not have API access. |
| 400 | unsupported_grant_type |
The grant_type is something other than client_credentials. |
| 400 | invalid_scope |
A scope parameter was sent. Scopes are not used, so leave this parameter out. |
The public sandbox credentials (api_test_user and api_test_key) cannot request access tokens because they do not belong to an organization. To try OAuth 2.0 in the sandbox, use your own organization's sandbox credentials.
API Endpoint Errors
When an access token is unknown or has expired, every other endpoint returns a 401 response with a WWW-Authenticate: Bearer error="invalid_token" header:
{
"success": 0,
"errors": [
{
"code": "invalid_token",
"message": "The access token is invalid or has expired"
}
]
}
Request a new access token and retry the call. If you continue having issues, please take a look at our troubleshooting guide.
Webhooks When OAuth 2.0 Is Required
Once your organization requires OAuth 2.0, webhooks become notifications only. Use them to learn that something happened, such as documents being notarized, then call our API to get the details and files you need. The webhooks we send you change in three ways:
- They are always JSON. Every webhook is sent as
application/json, never asmultipart/form-data. - They never include files. They do not include document links (
links_to_documents,link_to_documentorproof_of_address_links) or file attachments. Every other field stays the same. - They are signed, so you can verify that each one came from NotaryLive and was not modified. See Verifying Webhooks.
When you create an order with any API product, the request fails with a validation error unless:
company_emailis omitted, since order events are only sent by webhook.receive_files_as_attachmentsis omitted or false.webhook_urluseshttps.
Verifying Webhooks
Webhooks are signed with HMAC-SHA256 using your organization's webhook signing secret, which you can find on your API credentials page. The secret applies to all of your API products, in production and sandbox. Keep it private, the same way you keep your API key private.
Each webhook includes two headers:
| Header | Description |
X-NotaryLive-Timestamp |
When the webhook was sent, in Unix seconds. |
X-NotaryLive-Signature |
The signature, in the form sha256=<hex signature>. |
To verify a webhook:
- Build the signed content by joining the
X-NotaryLive-Timestampheader and the raw request body with a period:((timestamp)).((raw body)) - Compute the HMAC-SHA256 of the signed content, using your secret as the key, and hex-encode the result.
- Compare
sha256=followed by your result with theX-NotaryLive-Signatureheader, using a constant-time comparison such ascrypto.timingSafeEqualin Node.js orhmac.compare_digestin Python. - Reject the webhook if the timestamp is more than 5 minutes away from your current time. This prevents an attacker from resending an old webhook.
Only trust webhook events after verifying the signature and timestamp.
The signature is computed over the exact bytes we send. If your framework parses the JSON body and you serialize it again, whitespace or key order can change and the signature will not match. Always verify against the raw body.
For example, in Node.js:
const crypto = require("crypto");
// rawBody must be the request body exactly as received, before any JSON parsing
function verifyNotaryLiveWebhook(rawBody, headers, secret) {
const timestamp = headers["x-notarylive-timestamp"] || "";
const signature = headers["x-notarylive-signature"] || "";
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return false;
}
const expected = "sha256=" + crypto.createHmac("sha256", secret)
.update(timestamp + ".")
.update(rawBody)
.digest("hex");
const signatureBuffer = Buffer.from(signature);
const expectedBuffer = Buffer.from(expected);
return signatureBuffer.length === expectedBuffer.length
&& crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}
And in Python:
import hashlib
import hmac
import time
# raw_body must be the request body exactly as received, before any JSON parsing
def verify_notarylive_webhook(raw_body: bytes, headers, secret: str) -> bool:
headers = {name.lower(): value for name, value in headers.items()}
timestamp = headers.get("x-notarylive-timestamp", "")
signature = headers.get("x-notarylive-signature", "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
return False
signed_content = timestamp.encode() + b"." + raw_body
expected = "sha256=" + hmac.new(secret.encode(), signed_content, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature.encode(), expected.encode())
Copyright © 2026, NotaryLive.com