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.

​

Getting your API key

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

​

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:

​

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 Status Code 401

{
  "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 Status Code 403

{
  "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: 404

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

// HTTP Status Code 200

{
  "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:

• Create your first envelope using the API
• Explore the API playground to test requests interactively