Tirth API · Guide
Authentication
Every call to the Tirth API carries a key. The key says which company is calling, in which environment, and what it may do. Your data is reached only through your own keys.
Send your key
Send a secret key as a Bearer token in the Authorization header, on every request:
curl https://sandbox.api.tirth.com/v2/credit \
-H "Authorization: Bearer $TIRTH_API_KEY"In Node:
const response = await fetch('https://sandbox.api.tirth.com/v2/credit', {
headers: { Authorization: `Bearer ${process.env.TIRTH_API_KEY}` },
});A missing, malformed, unknown, revoked or expired key is 401 unauthenticated. So is a key sent to the wrong host: the sandbox takes only test keys and production only live keys, and the error's message names the right host.
Secret keys
| Environment | Starts with | Host |
|---|---|---|
| Sandbox | tirth_test_sk_ | sandbox.api.tirth.com |
| Live | tirth_live_sk_ | api.tirth.com |
- A secret key is its prefix, 32 random base62 characters and a 6-character base62 checksum. A key with a typo fails its checksum and is refused at once.
- It is shown once, when it is made. Tirth keeps only an HMAC-SHA256 of it, so nobody at Tirth can read it back; screens show its prefix and last 4 characters.
- It expires 12 months after it is issued.
- A live key needs two approvals at Tirth, one from platform and one from finance, before it is issued.
- Tirth's request logs keep IDs, status and timing, never your
Authorizationheader.
Keep secret keys on your servers. Never put one in a web page, a mobile app, a repository or a support message.
Publishable keys
A publishable key starts with tirth_pub_, followed by 24 base62 characters. It is meant for code people can read, such as a web page or an app, so it can hold only two scopes, catalogue:read and content:read: the catalogue and the calendar. It can never quote, book or read a booking.
Scopes
Each key carries scopes, and each operation needs one. The reference names the scope of every operation. A key without the scope an operation needs is 403 forbidden.
| Scope | What it allows |
|---|---|
catalogue:read | Pujas, samuhik pujas, packages, add-ons and search |
availability:read | Dates, sessions, departures and the availability changes feed |
quotes:write | Quotes, with seat holds |
bookings:write | Bookings, amendment quotes and amendments; in the sandbox, moving a booking on |
bookings:read | Bookings, the booking change feed, proof and refunds |
bookings:cancel | Cancellation quotes and cancellations |
credit:read | The credit balance, its transactions and monthly statements |
credit:topup | Telling Tirth of a top-up |
invoices:read | The GST documents Tirth issued to you |
webhooks:manage | Webhook endpoints and their deliveries |
cases:write | Cases about your bookings |
privacy:write | Privacy requests from your customers |
content:read | The calendar: cities, tithis and festivals |
checkout:write | Checkout sessions, for the Checkout tier when it opens |
Give each key only the scopes the system using it needs.
IP allowlists
A live secret key needs an IP allowlist before it can be issued when it holds any scope that writes, or bookings:read, invoices:read or privacy:write. The allowlist is a list of networks in CIDR form, such as 203.0.113.0/24. A call from outside the list is 403 forbidden; the reason is never sent back.
A key used from many residential or mobile addresses is suspended: call the API from your servers.
Two active keys and rotation
Each environment can hold two active secret keys at once, so you can rotate without a gap:
- Make a second key with the same scopes and allowlist.
- Deploy it to your servers and check your calls succeed with it.
- Revoke the old key. Calls with a revoked key are
401 unauthenticatedfrom then on.
Both active keys share one store of Idempotency-Keys, so a write retried across the switch still replays its first answer. Rotate at once if a key may have been seen by anyone else, and well before its 12 months end.
On the developer dashboard, making a key asks for a fresh sign-in code, and every admin of your company is told.
