Working with the API

This section covers how to authenticate with the Titus API, which environments are available, and best practices for making requests.

EnvironmentsCopied!

Titus provides two environments:

Environment	Base URL	Use Case
Production	`https://api.gotitus.com`	Live transactions
Staging	`https://api.gotitus.dev`	Integration testing

Your platform will have a different API key and webhook signing secret in each environment. Be sure to:

Use the correct base URL per environment
Configure separate webhook endpoints for each environment

Use the staging environment for testing and demo purposes. The staging environment:

Does not send out emails and SMS and other external communications. Uses 1234 for the login verification code.
Use the name Michael Scott in the application flow to bypass checks and always be auto-approved.
Does not perform actual credit checks and identity checks, so any SSN can be entered. Recommended to use 0000 for last 4 of SSN - this will be a high credit score user.
Does not trigger real payments. If prompted for bank information, feel free to enter any valid bank account information.

How to authenticate API callsCopied!

Titus uses API keys to authenticate requests.

Your API key is scoped to your platform
Include your key in the x-api-key header of every request

Example

GET /v1/checkouts HTTP/1.1
Host: api.gotitus.com
x-api-key: sk_live_abc123...
Content-Type: application/json

Never expose your API key on the client side.

API Request FormatCopied!

All requests to the Titus API must be made with application/json and include your API key in the headers.

Required Headers

x-api-key: Your platform’s secret API key
Content-Type: application/json

Conventions

All field names are in camelCase
All timestamps are ISO 8601 strings
Currency amounts are decimal numbers (e.g. 1000.00 for $1,000.00)

Example

POST /checkouts HTTP/1.1
Host: api.gotitus.com
x-api-key: sk_test_abc123...
Content-Type: application/json

{
  "orderId": "order_123",
  "businessId": "biz_456",
  "amount": 1500.00,
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel"
}

Error HandlingCopied!

Titus returns standardized error responses with helpful messages and structured fields.

Common Error CodesCopied!

Code	Meaning	Example Message
400	Bad Request	"Missing required field"
401	Unauthorized	"Invalid API key"
404	Not Found	"Checkout not found"
409	Conflict	"Checkout with orderId already exists"
500	Internal Error	"Internal server error"

{
  "error": "Conflict",
  "message": "Checkout with orderId already exists",
  "existingResourceId": "123"
}

Rate LimitCopied!

The limit is 100 requests per minute per IP. Exceeding the limit will return a 429 Too Many Requests response and will block subsequent requests until the minute window resets.