AutoSend API Keys: When should you use Account-Level (ASA_) vs Project-Level (AS_) keys?

API & SMTP Integration
1

What is the difference between AutoSend Account-Level API keys (prefixed with ASA_) and Project-Level API keys (prefixed with AS_), and when is passing an x-project-id header required?

2

AutoSend provides a two-tiered API key architecture designed for clear separation of concerns between organization-level provisioning and day-to-day email operations.

1. Project-Level API Keys (AS_...)

  • Key Prefix: AS_ (e.g., AS_prod_sec_abc123...)
  • Scope: Bound directly to a single specific Project (e.g., Production, Staging, or Client-A).
  • Primary Use Cases: Day-to-day runtime email workloads:
    • Sending emails (POST /v1/mails/send or POST /v1/mails/bulk)
    • Managing contacts, lists, segments, and suppression groups
    • Configuring templates, webhooks, and domain verification
  • Header Requirement: No need to provide a project identifier—the API key is cryptographically bound to its assigned project.
  • Limitations: Cannot create, inspect, or delete projects.

Example Request:

curl -X POST https://api.autosend.com/v1/mails/send \
  -H "Authorization: Bearer AS_your_project_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "email": "developer@example.com" },
    "from": { "email": "notifications@mail.yourdomain.com" },
    "subject": "Order Confirmation",
    "html": "<p>Thank you for your order!</p>"
  }'

2. Account-Level API Keys (ASA_...)

  • Key Prefix: ASA_ (e.g., ASA_org_root_sec_xyz789...)
  • Scope: Organization root / administrative access across all projects in the account.
  • Primary Use Cases:
    • Programmatic project provisioning (POST /v1/projects, GET /v1/projects, DELETE /v1/projects/{id})
    • Multi-tenant SaaS architectures where projects are created dynamically for new customer workspaces.
    • Organization-wide admin automations.
  • The x-project-id Header Rule:
    • Creating Projects: You do not need the x-project-id header when calling POST /v1/projects because the new project does not exist yet.
    • Operational Endpoints: If you use an ASA_ key to perform actions on operational endpoints (such as sending emails or listing contacts), you must pass the target Project ID via the x-project-id header, otherwise AutoSend cannot determine which workspace to execute against:
curl -X POST https://api.autosend.com/v1/mails/send \
  -H "Authorization: Bearer ASA_your_account_api_key" \
  -H "x-project-id: prj_your_project_id" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "email": "developer@example.com" },
    "from": { "email": "notifications@mail.yourdomain.com" },
    "subject": "Admin Dispatched Email",
    "html": "<p>Sent via Account Key with x-project-id header.</p>"
  }'

:light_bulb: Best Practice Architecture

  1. Application Runtimes: Use Project Keys (AS_) in your backend servers, Next.js / Remix / Astro apps, and serverless workers. Store them in AUTOSEND_API_KEY.
  2. DevOps & Multi-Tenant Provisioning: Use Account Keys (ASA_) strictly in CI/CD pipelines, infrastructure-as-code scripts, or backend multi-tenant tenant onboarding services.

Relevant Documentation