# Authentication for TopSMS (topsms.eu)

TopSMS is a Czech A2P SMS gateway for businesses. This file explains how automated clients
and AI agents authenticate. Machine-readable API description: https://topsms.eu/openapi.yaml
Human documentation: https://topsms.eu/docs (English), https://topsms.eu/de/docs (German), https://www.topsms.cz/api-integrace/rest-api (Czech).

## Registration

Accounts are created by a person at https://www.topsms.cz/?registrace (Czech), https://topsms.eu/ (English)
or https://topsms.eu/de (German). Registration requires a name, e-mail, a mobile number that is verified
with a one-time SMS code, and acceptance of the terms of service. There is no API for creating accounts
and automated registration is not permitted.

## API keys

A logged-in user creates API keys in the dashboard (Dashboard -> API). Each key has a client ID and a
secret; the secret is shown once. Keys can be limited to scopes (send, read) and can have a webhook URL
for delivery reports.

## Authenticating API requests

Every request to https://www.topsms.cz/api/sms/* and the other API endpoints carries:

    Authorization: Bearer <clientId>:<secret>

Example:

    curl -X POST https://www.topsms.cz/api/sms/send \
      -H "Authorization: Bearer CLIENT_ID:SECRET" \
      -H "Content-Type: application/json" \
      -d '{"to": "+420601234567", "text": "Hello", "from": "TopSMS"}'

Missing or invalid credentials return HTTP 401 with a JSON error. Requests are rate-limited per key
(HTTP 429 when exceeded). OAuth is not offered.

## Sessions and browser login

The web dashboard uses a session cookie after login at https://www.topsms.cz/login (password, optional
two-factor code by SMS, or Google sign-in). Session cookies are not meant for API clients; use an API key.

## Contact

info@topsms.cz