> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>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.</Warning>

## Getting your API key

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

<Steps>
  <Step title="Sign Up">
    [Sign up](https://accounts.signatureapi.com/sign-up) for a free account on SignatureAPI.
  </Step>

  <Step title="Get your API key">
    Navigate to the SignatureAPI [Dashboard](https://dashboard.signatureapi.com/settings/api-keys) and copy your test API key from the API Keys section.
  </Step>
</Steps>

## 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:

```json theme={null}
// 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 Type  | Format         | Purpose                                                 |
| --------- | -------------- | ------------------------------------------------------- |
| Test keys | `key_test_...` | Development and testing without real legal consequences |
| Live keys | `key_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](/docs/api/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.

```json theme={null}
// 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](/docs/v1/errors/invalid-api-key)

### Forbidden Access

**HTTP Status Code: 403**

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

```json theme={null}
// 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](/docs/v1/errors/forbidden)

### Test/Live Mode Mismatch

**HTTP Status Code: 404**

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

```json theme={null}
// 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](/docs/v1/errors/mode-error)

## Next steps

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

* [Create your first envelope](/docs/api/quickstart) using the API
* [Explore the API playground](/docs/api/playground) to test requests interactively