Coritan API

The Coritan API lets a script or an agent do what you do in the dashboard: order and manage services, pay invoices, edit DNS records and write to support. It is a REST API over HTTPS that takes and returns JSON, and the dashboard is built on the same endpoints.

Every request goes to one base URL:

https://api.coritan.com/api/v1

Client API

Your own account: services, billing, DNS, support and everything else the dashboard shows you. Its paths start with /api/v1, such as /api/v1/services/, and it takes the access token you get by signing in.

Organization API

An organization that sells Coritan services under its own brand. Its members manage it with their own access token, and its storefront and its customers use it too. Its paths start with /api/v1/orgs/{org_slug}, where {org_slug} is the organization's short name.

Authentication lists which credential each part of either API accepts.

Sign in with POST /auth/login to get an access token, as Make your first API request shows step by step. Put the token in CORITAN_TOKEN, then read your account:

curl https://api.coritan.com/api/v1/auth/me \
  -H "Authorization: Bearer $CORITAN_TOKEN"

{
  "id": 4821,
  "email": "alex@example.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "status": "active",
  "credit_balance": 25.0,
  "currency": "USD"
}

A request without a valid token answers 401 or 403 with a detail that says why (Errors).

• Authentication: access and refresh tokens, how long they last, and the keys some parts of the Organization API take.
• Errors: the status codes and the shapes of detail.
• Rate limits: how many requests you can send, and what to do with a 429.
• Pagination and filtering: how lists are paged and filtered.
• Idempotent requests: the Idempotency-Key header, so a retried payment or order happens once.

The API can answer a read from a copy of its data that is a little behind, so a read sent straight after a change may not show it yet. An answer to a request that saved a change can carry a Coritan-Wrote-At header. Send its value back as Coritan-Read-After on the requests that follow, and they read the latest data.

This changes the company on your account with PUT /auth/me, then reads the account back:

WROTE_AT=$(curl -s -o /dev/null -D - \
  -X PUT https://api.coritan.com/api/v1/auth/me \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company": "Example Ltd"}' \
  | awk 'tolower($1) == "coritan-wrote-at:" {print $2}' | tr -d '\r')

curl https://api.coritan.com/api/v1/auth/me \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Coritan-Read-After: $WROTE_AT"

• The value is when the API saved the change, in milliseconds since Jan 1, 1970 (UTC). Send it exactly as you received it.
• It counts for 10 seconds after the change. The API ignores a value that is older than that, more than 5 seconds ahead of its own clock, or not a whole number, and answers the request as usual.
• An answer without the header leaves nothing to send.
• The header changes only where the API reads your data from.
• A page in a browser that can call the API can read Coritan-Wrote-At and send Coritan-Read-After.
• The dashboard does this for you, and so does the @coritan/commerce SDK for later requests from the same client.

The API reference lists every operation with its parameters, request body and responses, generated from the API itself:

• Client API reference
• Organization API reference

Each API also has an interactive reference, where you can send requests from the browser: the Client API and the Organization API.

Every page of these docs is also plain Markdown, for a script or an AI agent to read:

The API is free to use. You pay for the services you order through it, exactly as in the dashboard (Billing). The API is open to every account, and an organization's API is open to its members.