aethexDocs
Dashboard

API Reference

Twilio Accounts API

Register and manage the Twilio accounts that Aethex uses to drive your Twilio phone numbers. Each account can hold up to 32 active Twilio accounts at once. Register one of these before calling POST /phone-numbers/twilio/register; the id returned here is the twilio_account_id required on that endpoint. The supplied auth_token is verified against Twilio at registration, then stored encrypted at rest and never returned in any response body or log line. Requires twilio_accounts:read or twilio_accounts:write scope. The same account sends your text messages. There is nothing to link twice and no messaging provider to choose: you designate which of your numbers texts from, and whether it receives texts, on the number itself with PATCH /phone-numbers/{id} and sms_sender / sms_inbound. Twilio is asked whether the number can carry texts, and a voice-only line is refused. What an agent may say is written separately, under Text messages.

Base URL
https://api.aethexai.com/api/v1
Endpoints
4
Scopes
twilio_accounts:readtwilio_accounts:write
POST/twilio-accounts

Validate a Twilio Account SID/Auth Token pair against Twilio, then store it encrypted for outbound dial and inbound webhook verification.

Register Twilio Account

Validates the supplied account_sid and auth_token against Twilio, then persists the credentials and returns the new record. The auth_token is write-only and never appears in any response or log line. account_sid accepts mixed-case hex on input and is canonicalised to lowercase before storage. Per-account rate limit: 5 registrations per 60 seconds. Active accounts are hard-capped at 32 per account. The same Twilio Account SID cannot be claimed by two accounts at the same time.

Request body

3
  • account_sidstringrequired

    Twilio Account SID; literal AC followed by exactly 32 hexadecimal characters. Case-insensitive on input; canonicalised to lowercase before storage. Total length must be 34 characters.

  • auth_tokenstringrequired

    Twilio Auth Token (1–128 chars). Write-only: validated against Twilio at registration, stored encrypted at rest, and never returned in any response body.

  • friendly_namestringoptional

    Human-readable label rendered in the developer portal (max 255 chars). Plain text only; control characters and HTML markup are rejected.

Errors

8
422Invalid SID format

account_sid is not literal AC followed by exactly 32 hex characters, or auth_token / friendly_name violate their length or content rules.

Copy the Account SID exactly from the Twilio console; trim whitespace; keep friendly_name to plain text under 255 chars.

422Twilio rejected the credentials

Twilio responded with an authorisation error; bad Auth Token, revoked token, or the token does not authorise access to the supplied SID.

Re-copy the Auth Token from the Twilio console, and confirm both values come from the same Twilio account.

422Twilio Account SID not found

The supplied account_sid does not exist on Twilio. Typically a typo or a deleted account.

Re-paste the Account SID from the Twilio console; do not retype it by hand.

409Account SID already registered for this account

This account already has an active row for the same account_sid.

Keep using the existing registration, or DELETE /twilio-accounts/{account_id} first and then re-register.

409Account SID claimed by another account

A different account already holds an active row for this account_sid.

Have the previous owner release the SID via DELETE /twilio-accounts/{account_id}, or open a support ticket.

409Active account cap reached

Your account already has 32 active Twilio accounts.

Release an unused account via DELETE /twilio-accounts/{account_id} before registering a new one.

429Registration rate limit

More than 5 POST /twilio-accounts calls from this account in the last 60 seconds.

Wait the number of seconds in Retry-After, then retry. If you legitimately need to register many accounts, do so serially with a short delay.

503Twilio API unreachable

Twilio did not respond within the validation deadline, or returned a 5xx.

Retry shortly. If Twilio is reporting an incident, wait until it clears.

GET/twilio-accounts

Paginated list of every active Twilio account on your account.

List Twilio Accounts

Returns every active Twilio account on your account, ordered by created_at descending. Released accounts are filtered out. Standard offset/limit pagination. Requires twilio_accounts:read scope.

Path & Query

2
  • offsetintegeroptional

    Number of results to skip (default: 0; minimum: 0).

  • limitintegeroptional

    Maximum number of results to return (default: 50; minimum: 1; maximum: 200).

Errors

1
422Invalid pagination parameter

offset is negative, or limit is below 1 or above 200.

Send offset >= 0 and 1 <= limit <= 200.

GET/twilio-accounts/:account_id

Fetch a single Twilio account on your account by UUID.

Get Twilio Account

Account-scoped lookup by primary key. Released accounts are reported as not found. Requires twilio_accounts:read scope.

Path & Query

1
  • account_idstringrequired

    Twilio account UUID (the id field from the registration response).

Errors

2
404Twilio account not found

No active row with the given UUID exists on this account. A row owned by another account is also reported as not found.

Confirm the account_id came from this account's GET /twilio-accounts response and that you have not released it.

422Invalid UUID

account_id path parameter is not a valid UUID.

Pass the id field returned by POST or GET /twilio-accounts.

DELETE/twilio-accounts/:account_id

Idempotent release that flips the row to `released` and scrubs the stored auth token.

Release Twilio Account

Flips status from active to released, freeing the Account SID so it can be re-registered later (handy for account-transfer scenarios), and destroys the stored auth token so the original credential cannot be recovered. Phone numbers already registered under this account remain visible but will fail at dial time once the credentials are gone. Idempotent: returns 204 No Content whether the row was active, already released, or never existed under this account. Requires twilio_accounts:write scope.

Path & Query

1
  • account_idstringrequired

    Twilio account UUID.

Errors

1
422Invalid UUID

account_id path parameter is not a valid UUID.

Pass the id field returned by POST or GET /twilio-accounts.