Twilio error 20003 "Authenticate" in CI

By Daniel Zoghalchali·Latchkey

Twilio returns HTTP 401 with error code 20003 "Authenticate" when the Account SID and Auth Token used for basic auth are missing or incorrect. In CI this means the TWILIO_ACCOUNT_SID or TWILIO_AUTH_TOKEN secret is empty, mistyped, or was rotated.

What this error means

A Twilio Messages API call returns HTTP 401 with {"code":20003,"message":"Authenticate"}. No SMS alert is sent.

< HTTP/1.1 401 Unauthorized
{"code": 20003, "message": "Authenticate", "more_info": "https://www.twilio.com/docs/errors/20003", "status": 401}

Common causes

Missing or wrong SID/token

One of the two basic-auth values is empty or mistyped, so Twilio cannot authenticate the request.

The Auth Token was rotated

Rotating the primary Auth Token invalidates the old value; the stored secret still holds it.

How to fix it

Authenticate with SID and token

1. Copy the Account SID and Auth Token from the Twilio console.
2. Store both as CI secrets.
3. Pass them as HTTP basic auth to the Messages endpoint.

curl -sS -X POST \
  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
  --user "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  --data-urlencode "To=+15558675310" \
  --data-urlencode "From=$TWILIO_FROM" \
  --data-urlencode "Body=CI build failed"

Reference the secrets in the step

Expose both values through the step env from the correct secret names.

env:
  TWILIO_ACCOUNT_SID: ${{ secrets.TWILIO_ACCOUNT_SID }}
  TWILIO_AUTH_TOKEN: ${{ secrets.TWILIO_AUTH_TOKEN }}

How to prevent it

• Store the SID and token as secrets without trailing whitespace.
• Rotate the token and update the secret together.
• Prefer an API key SID/secret over the primary Auth Token where possible.

Frequently asked questions

Related guides

References

• GitHub Actions documentation