# Authentication

Securely authenticate your requests to the Emailable API.

## Overview

```shell
# Using api_key parameter
curl "https://api.emailable.com/v1/api_endpoint?api_key=YOUR_API_KEY"

# Using Authorization header
curl "https://api.emailable.com/v1/api_endpoint" -H "Authorization: Bearer YOUR_API_KEY"
```

```ruby
# Global
Emailable.api_key = 'YOUR_API_KEY'

# At request time
Emailable.verify('john@smith.com', api_key: 'YOUR_API_KEY')
```

```javascript
// Global: Common JS import
const emailable = require('emailable')('YOUR_API_KEY');

// Global: ES6 import
import Emailable from 'emailable';
const emailable = Emailable('YOUR_API_KEY');

// At request time
emailable.verify('john@smith.com', { apiKey: 'YOUR_API_KEY' });
```

```python
# Global
client = emailable.Client('YOUR_API_KEY')

# At request time
client.verify('john@smith.com', api_key='YOUR_API_KEY')
```

> Make sure to replace `YOUR_API_KEY` with your actual API key.

Emailable uses API keys to allow access to our API. To get started, sign up for an account [here](https://app.emailable.com/signup?utm_source=api-docs&utm_medium=web&utm_campaign=authentication_section).

Emailable expects the API key to be included in all API requests to the
server as a URL parameter, or as POST data for POST endpoints.

Alternatively, you can use an HTTP Authorization header with your API key. In the header, specify the Bearer scheme followed by your API key. (e.g. `"Authorization: Bearer YOUR_API_KEY"`).

## Security

Emailable has two types of API Keys. Please use the proper API key for your application.

### Private API Keys

This type of key is meant to be used on the server-side of your application.
These keys should never be exposed because they are not protected.

Should a Private API key be compromised, you should immediately generate a new
one by using the "roll key" function in the dashboard.

To enhance security, you can specify a list of trusted IP addresses for each
Private API key. If specified, only requests originating from one of the IP
addresses you have listed will be accepted.

Private API keys can be used to access any API endpoint.

### Public API Keys

This type of key is meant to be used anywhere that the key will be exposed
publicly. One example would be using the API in the JavaScript of a website to
verify that user entered email addresses are valid.

To prevent abuse of your account, we require that you set up a list of
trusted domains when you create a Public API key. All requests that are made
using a Public API key will only work if they originate from a trusted domain.
They will also be rate limited to 10 unique requests per day per user.

If you've configured a captcha provider for your API key, you will need to
send a `captcha_response` parameter with the request. This will be used to
validate the captcha with your captcha provider. If the captcha fails to
verify, the API will return a `403` status code.

Public API keys are limited to authenticating requests to the `/verify`
endpoint. Attempting to use a Public API key for any other endpoint will fail.

## Testing

For either type of API key (Public or Private), a test key can be used instead
of a live key. When creating an API key, you will be asked whether you want to
create a test key or a live key. If you choose to create a test key, the key
you generate will begin with `"test_"` instead of `"live_"`.

Any requests made with a test key will not use credits or perform real
verifications. Instead, a simulated response will be returned.  This is useful
for testing whether your application is correctly making API calls without
having to waste credits.

You can also use a test key with certain test email addresses to generate
responses with specific attributes. This is documented in [Emails](/docs/api/emails#test-email-addresses).

Batches created with a test key will be automatically deleted after 24 hours.

Trusted IP address and trusted domain restrictions will still apply to test
keys. Domain-based rate limits for Public API keys are not enforced for test
keys.

## OAuth Apps

```shell
# Using access_token parameter
curl "https://api.emailable.com/v1/api_endpoint?access_token=YOUR_ACCESS_TOKEN"

# Using Authorization header
curl "https://api.emailable.com/v1/api_endpoint" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```ruby
Emailable.verify('john@smith.com', access_token: 'YOUR_ACCESS_TOKEN')
```

```javascript
emailable.verify('john@smith.com', { accessToken: 'YOUR_ACCESS_TOKEN' });
```

```python
client.verify('john@smith.com', access_token='YOUR_ACCESS_TOKEN')
```

> Make sure to replace `YOUR_ACCESS_TOKEN` with the access token.

If you've authenticated a user with an OAuth App, you should have an access
token for that user. You can use the access token to authenticate to the
Emailable API by sending an `access_token` parameter instead of an `api_key`
parameter. Alternatively, you can use an HTTP Authorization header with the
access token. In the header, specify the Bearer scheme followed by the access
token. (e.g. `"Authorization: Bearer YOUR_ACCESS_TOKEN"`).

See [OAuth](/docs/api/oauth) for more information on OAuth endpoints, including
instructions for obtaining an access token.