OAuth 2.0 Authentication

Page last updated: October 27, 2026

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.

NotaryLive API - OAuth 2.0 Authentication

Documentation

Endpoints

eSign API

IPEN API