Authentication

Every request carries an API key of your account as a bearer token:

GET /v1/messages HTTP/1.1
Host: api.ace-send.com
Authorization: Bearer ak_live_8f2kX3m0QpLr7VtN1yHcB5dW9sJ4eA6u

There are no sessions or cookies. A key works only on api.ace-send.com.

API keys

Keys are created in the console, Settings → API and webhooks, by the account owner or a developer. Creating or rolling a key needs two-factor authentication on the user, and while the account has active keys at least one owner must keep two-factor authentication on.

Format	ak_live_ or ak_test_ and 32 letters and digits
Shown	once, when created or rolled. Afterwards the console shows its first characters only
Active keys	up to 10 per account
Mode	Live sends for real; Test sends through the free sandbox
Permissions	one or more of send, status, contacts
IP allowlist	optional: up to 20 addresses or networks

Keep keys on your servers only — never in a mobile app, a browser or a repository. Use one key per system (CRM, payments, game backend): you can see when each was last used, and revoke one without touching the others.

Permissions

Permission	Endpoints
send	POST /v1/messages, GET /v1/templates
status	GET /v1/messages, GET /v1/messages/{id}
contacts	GET /v1/fields, POST /v1/contacts

A new key has send and status. A request outside the permissions of its key gets 403 api_key_scope.

IP allowlist

A key with an allowlist works only from those addresses; elsewhere it gets 403 api_key_ip_denied. Entries are IPv4 or IPv6 addresses (203.0.113.7) or networks in CIDR notation (203.0.113.0/24, 2001:db8::/32). A network must be written with its first address: 203.0.113.0/24, not 203.0.113.7/24. An empty list allows any address.

We recommend an allowlist for every live key whose servers have fixed addresses.

Rolling and revoking

• Roll issues a new key with the same name, mode, permissions and allowlist, and revokes the old one at once. Deploy the new key right after rolling.
• Revoke stops the key at once. Revoked keys get 401 api_key_invalid.

If a key leaks, revoke or roll it immediately.

Errors

The key is checked in this order:

Status	Code	Why
429	too_many_requests	20 requests with invalid keys from your address within a minute
401	api_key_invalid	no Authorization: Bearer header, or an unknown or revoked key
403	api_key_ip_denied	the request came from an address outside the allowlist of the key
403	account_suspended	the account is suspended — contact support
403	api_key_scope	the key lacks the permission of the endpoint

A 401 answer carries WWW-Authenticate: Bearer.