SignatureAPI
Mint Starter Kit

Reference

Authentication

Learn how to authenticate your API requests with SignatureAPI

SignatureAPI uses API key authentication to secure access to your account and ensure only authorized requests can create, modify, or access your envelopes and documents.

How authentication works

All API requests require authentication using an API key passed in the X-API-Key header.

When you make a request, SignatureAPI validates your API key and determines which account and environment (test or live) the request should access.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Getting your API key

You can get a free test API key to try out SignatureAPI and set up your workflow:

1

Sign Up

Sign up for a free account on SignatureAPI.

2

Get your API key

Navigate to the SignatureAPI Dashboard and copy your test API key from the API Keys section.

Making authenticated requests

Include your API key in the X-API-Key header with every request. Here’s how to authenticate when creating an envelope:

// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json

{
  "title": "Employment Agreement",
  //...
}

API key types

SignatureAPI provides different API key types for different environments:

Key TypeFormatPurpose
Test keyskey_test_...Development and testing without real legal consequences
Live keyskey_live_...Production use with legally-binding documents

Test mode benefits

Test API keys let you create test envelopes, perfect for trying out your workflows. Envelopes in test mode:

  • Don’t send emails to recipients (you can preview them in your dashboard)
  • Are not legally-binding, so no legal obligations arise during testing
  • Are completely free to use
  • Have all the same API functionality as live mode

Learn more about Test Mode.

Authentication errors

When authentication fails, you’ll receive specific error responses to help you diagnose the issue:

Invalid API Key

The API key provided is not valid or improperly formatted.

// HTTP/1.1 401 Unauthorized
{
  "type": "https://signatureapi.com/docs/v1/errors/invalid-api-key",
  "title": "Invalid API Key",
  "status": 401,
  "detail": "Please provide a valid API key in the X-API-Key header."
}

Common causes:

  • Missing or incomplete API key
  • API key not passed in the X-API-Key header
  • Typos in the API key value

Learn more about Invalid API Key errors

Forbidden Access

HTTP Status Code: 403

Your API key is valid but doesn’t have permission to access the requested resource.

// HTTP/1.1 403 Forbidden
{
  "type": "https://signatureapi.com/docs/v1/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The requested resource exists, and the API key is valid, but the API key does not have permission to access it."
}

Common causes:

  • Using an API key from a different account
  • Insufficient permissions for the requested operation

Learn more about Forbidden errors

Test/Live Mode Mismatch

HTTP Status Code: 403

You’re trying to access a resource with the wrong environment key (test vs live).

// HTTP/1.1 403 Forbidden
{
  "type": "https://signatureapi.com/docs/v1/errors/mode-error",
  "title": "Mode Error",
  "status": 403,
  "detail": "You are trying to access a test-mode resource with a live API key. Please use a test API key."
}

Common causes:

  • Using a test API key to access live resources
  • Using a live API key to access test resources

Learn more about Mode errors

Next steps

Now that you understand authentication, you’re ready to: