Authentication and API keys
Authenticate server-side requests, understand authorization failures, and handle keys and access links correctly.
Send a Bearer token
Use the same headers across JSON operations. The published API v2 base URL is https://app.bluenotary.us/api/integrationsv2.
curl --request GET \
"$BN_API_BASE_URL/sessions/$BN_SESSION_ID" \
--header "Authorization: Bearer $BN_API_KEY" \
--header "Content-Type: application/json"Keep credentials on your server
Your application backend calls the API. The browser receives only the participant link needed for that authorized user, never your vendor API key.
- Browser requests a signing action
Authenticate the application user and validate their access to the order.
- Backend creates or retrieves the session
Read the API key from your server secret configuration.
- Backend returns the correct participant link
Match the application user to the intended signer before returning access.
Handle authentication failures
Missing, empty, expired, or invalid API keys return 401. Treat an authentication failure as a configuration issue instead of repeating the same request indefinitely.
| Response | Likely cause | Action |
|---|---|---|
| 401 | Missing Authorization header | Send the Bearer header from the backend. |
| 401 | Invalid or expired key | Check the configured key and rotate or replace it. |
| 403 on a session route | Session is absent, deleted, or belongs to another vendor | Check the BlueNotary session ID and owning account. |
| 400 on a session route | Malformed session identifier | Use the returned bn_session_id. |
Plan key rotation
Store keys in your normal secrets system. Coordinate replacement with your account’s supported key-management flow, update services, confirm a successful authorized request, and then retire the old credential.
- Avoid putting keys in source control, query strings, screenshots, or support messages.
- Redact Authorization headers from application logs.
- Check key expiry before production release.
- Do not assume legacy keys have the same environment behavior as newer sandbox/production keys.
Signing links are credentials too
Returned signing links, dashboard login links, and onboarding links serve different purposes. All should be delivered only to their intended recipient.
| Link | Purpose | Important behavior |
|---|---|---|
| signing_urls | Access to a session | Map the link to the right participant and product flow. |
| login_link | Account login | Current verifier allows reuse until its 12-hour expiry. |
| onboarding_link | Team onboarding | Regeneration rotates the session password and can invalidate older links. |