All Ark API requests require authentication using an API key. This guide covers how to create, use, and manage your API keys.
API Key Authentication
Ark uses Bearer token authentication. Include your API key in the Authorization header of every request:
Authorization: Bearer ark_live_xxxxxxxxxxxxxxxxxxxx
Keep your API keys secure. Never expose them in client-side code, public repositories, or logs. Treat API keys like passwords.
Getting Your API Key
API Key Types
| Type | Prefix | Usage |
|---|
| Live | ark_live_ | Production environment |
| Test | ark_test_ | Development and testing |
Use test keys during development. They work identically to live keys but won’t send actual emails.
Using the SDKs
The recommended way to authenticate is using an official SDK. All SDKs automatically handle authentication:
Python
Node.js
Ruby
Go
cURL
from ark import Ark
# Option 1: Pass API key directly
client = Ark(api_key="ark_live_xxxxxxxxxxxxxxxxxxxx")
# Option 2: Use environment variable (recommended)
# Set ARK_API_KEY in your environment, then:
client = Ark() # Automatically uses ARK_API_KEY
# Send an email
email = client.emails.send(
from_="[email protected]",
to=["[email protected]"],
subject="Hello",
html="<p>Hello!</p>"
)
import Ark from 'ark';
// Option 1: Pass API key directly
const client = new Ark({ apiKey: 'ark_live_xxxxxxxxxxxxxxxxxxxx' });
// Option 2: Use environment variable (recommended)
// Set ARK_API_KEY in your environment, then:
const client = new Ark(); // Automatically uses ARK_API_KEY
// Send an email
const email = await client.emails.send({
from: '[email protected]',
to: ['[email protected]'],
subject: 'Hello',
html: '<p>Hello!</p>',
});
require "ark_email"
# Option 1: Pass API key directly
client = ArkEmail::Client.new(api_key: "ark_live_xxxxxxxxxxxxxxxxxxxx")
# Option 2: Use environment variable (recommended)
# Set ARK_API_KEY in your environment, then:
client = ArkEmail::Client.new # Automatically uses ARK_API_KEY
# Send an email
email = client.emails.send_(
from: "[email protected]",
to: ["[email protected]"],
subject: "Hello",
html: "<p>Hello!</p>"
)
import (
"github.com/ArkHQ-io/ark-go"
"github.com/ArkHQ-io/ark-go/option"
)
// Option 1: Pass API key directly
client := ark.NewClient(option.WithAPIKey("ark_live_xxxxxxxxxxxxxxxxxxxx"))
// Option 2: Use environment variable (recommended)
// Set ARK_API_KEY in your environment, then:
client := ark.NewClient() // Automatically uses ARK_API_KEY
// Send an email
email, _ := client.Emails.Send(ctx, ark.EmailSendParams{
From: "[email protected]",
To: []string{"[email protected]"},
Subject: "Hello",
HTML: ark.String("<p>Hello!</p>"),
})
curl https://api.arkhq.io/v1/emails \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Hello",
"html": "<p>Hello!</p>"
}'
Authentication Errors
When authentication fails, the SDK will throw an AuthenticationError:
import ark
try:
client = Ark(api_key="invalid_key")
client.emails.send(...)
except ark.AuthenticationError as e:
print(f"Authentication failed: {e.message}")
import Ark from 'ark';
try {
const client = new Ark({ apiKey: 'invalid_key' });
await client.emails.send({...});
} catch (error) {
if (error instanceof Ark.AuthenticationError) {
console.log(`Authentication failed: ${error.message}`);
}
}
begin
client = ArkEmail::Client.new(api_key: "invalid_key")
client.emails.send_(...)
rescue ArkEmail::Errors::AuthenticationError => e
puts "Authentication failed: #{e.message}"
end
client := ark.NewClient(option.WithAPIKey("invalid_key"))
_, err := client.Emails.Send(ctx, params)
if err != nil {
var arkErr *ark.Error
if errors.As(err, &arkErr) && arkErr.StatusCode == 401 {
fmt.Printf("Authentication failed: %s\n", arkErr.Message)
}
}
Common Causes
| Error | Cause | Solution |
|---|
authentication_required | Missing Authorization header | Add Authorization: Bearer <key> header |
invalid_api_key | Key format is incorrect | Ensure key starts with ark_live_ or ark_test_ |
expired_api_key | Key has been revoked | Generate a new key from your dashboard |
Best Practices
Use Environment Variables
Never hardcode API keys. Use environment variables:
export ARK_API_KEY="ark_live_xxxxxxxxxxxxxxxxxxxx"
import os
from ark import Ark
# SDK automatically reads ARK_API_KEY
client = Ark()
# Or explicitly read it
client = Ark(api_key=os.environ.get("ARK_API_KEY"))
import Ark from 'ark';
// SDK automatically reads ARK_API_KEY
const client = new Ark();
// Or explicitly read it
const client = new Ark({ apiKey: process.env.ARK_API_KEY });
Rotate Keys Regularly
- Generate a new key in your dashboard
- Update your application with the new key
- Revoke the old key once the new one is deployed
Use Separate Keys per Environment
Create different keys for:
- Development (test keys)
- Staging (test keys)
- Production (live keys)
This limits blast radius if a key is compromised.
Restrict Key Permissions
When creating keys, grant only the permissions you need:
| Permission | Description |
|---|
emails:send | Send emails |
emails:read | Read email status and details |
domains:manage | Create and configure domains |
webhooks:manage | Create and configure webhooks |
suppressions:manage | Manage suppression list |
Rate Limits
API keys are subject to rate limits. See Rate Limits for details.
Next Steps
