Authentication

Every request must carry your secret API key in the x-api-key header. A key is issued per organization and scopes all data to that organization, so you never pass an organization id explicitly.

curl

curl https://api.sms.noticia.ai/v1/profiles \
  -H "x-api-key: ntca_REPLACE_ME"

JavaScript

const response = await fetch('https://api.sms.noticia.ai/v1/profiles', {
  headers: { 'x-api-key': 'ntca_REPLACE_ME' },
});

Python

import requests

response = requests.get(
    "https://api.sms.noticia.ai/v1/profiles",
    headers={"x-api-key": "ntca_REPLACE_ME"},
)

Keys are prefixed with ntca_. The prefix is reserved: an externalId you send may never start with it.

Keep keys server-side

An API key grants full read and write access to your organization’s data. Use it from your backend, your CRM connector, or your POS middleware. Never ship it in a client-side bundle or any environment you do not fully control (a public web page, a distributed mobile app), where an end user could extract it.

Errors

A missing or bad key returns 401 with a stable code you can branch on:

Code	Meaning
AUTH_MISSING_API_KEY	No x-api-key header was sent.
AUTH_INVALID_API_KEY	The key does not match any active key.
AUTH_REVOKED_API_KEY	The key was revoked.
AUTH_EXPIRED_API_KEY	The key passed its expiry date.

{
  "code": "AUTH_INVALID_API_KEY",
  "message": "The provided API key is not valid.",
  "requestId": "b3f1c8d2-2b9e-4c5e-8a1f-2c7d6a9e4b1a"
}

See the errors reference for the full catalog.

Environments

A Noticia organization runs in DEMO or PRODUCTION. The same API key and the same integration work in both: you never rebuild your integration when you go live.

Mode	Data	SMS sends
DEMO	Your real data, pushed through the API	Simulated
PRODUCTION	Your real data	Real

In DEMO, SMS sends are simulated end to end so you can validate the full flow (segments, journeys, attribution) without sending a single real message. Promotion to PRODUCTION keeps the data you pushed. Read Demo and Production for the full model.

Rotation

Rotate keys on a schedule and whenever a team member with access leaves.

1. Create a new key in Integrations -> API keys.
2. Deploy it to your integration.
3. Confirm traffic flows on the new key.
4. Revoke the old key.

Because you cut over before revoking, there is no downtime.

A key has leaked

If a key is exposed (committed to a repository, pasted in a ticket, logged in plaintext):

1. Revoke it immediately in Integrations -> API keys. Revocation takes effect at once and every later request with that key returns AUTH_REVOKED_API_KEY.
2. Create a replacement key and deploy it.
3. Review recent activity for anything you did not initiate and contact support if you need help auditing.