Public REST API

Use the cside Public REST API to provision teams and managed domains from a backend workflow. The API uses JSON over HTTPS and an organization-level bearer token.

Base URL: https://api.cside.com

Provisioning flow

Team creation and domain registration are separate operations:

1. Create an organization API token with the required permissions
2. Call POST /v1/teams/ and save the returned teamId
3. Call POST /v1/domains/ with that teamId and up to 100 hostnames
4. Check every item in data.results before treating the provisioning run as complete

If domain registration fails, the team remains available. The API does not roll back a successful team creation.

Availability and authentication

An organization administrator can generate a token from **Organization Settings

General** in the cside dashboard. Choose only the permissions the integration needs:

Permission	API access
Create teams (teams:create)	POST /v1/teams/
Register domains (domains:create)	POST /v1/domains/
Delete domains (domains:delete)	DELETE /v1/domains/

The dashboard shows each token once. Store it in a server-side secret manager before closing the dialog. Do not expose it in browser code, commit it to source control, or write it to application logs.

Send the token with every request:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Tokens remain valid until an administrator selects Revoke all tokens. That action immediately invalidates every API token for the organization.

Rate limit

The API accepts 60 requests per organization per minute. This limit is shared across team and domain endpoints. A request above the limit returns 429 with the rate_limited error code. Retry with backoff after the next minute begins.

Create a team

Use POST /v1/teams/ to create a team under the token’s organization.

curl --request POST \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Acme Production"
  }'

The team name must:

• Contain 3 to 32 characters
• Use letters, numbers, underscores, spaces, or apostrophe characters
• Be unique within the organization

Hyphens are not accepted in team names.

A successful request returns 201 Created:

{
  "data": {
    "teamId": "1897425263682514944"
  }
}

Save data.teamId. You need it to register or delete domains for the team.

Creating a team does not enable automatic domain onboarding. That capability is configured separately for each team and is disabled by default.

Register domains

Use POST /v1/domains/ to register 1 to 100 managed domain hostnames for a team. team_id is required when you use an organization API token.

curl --request POST \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "checkout.example.com",
      "app.example.com"
    ]
  }'

Send hostnames without a protocol, port, path, query string, or fragment. cside trims whitespace and normalizes accepted hostnames to lowercase.

Each item registers the exact hostname you send. The API does not create a wildcard domain, so include every hostname you need, such as both example.com and www.example.com.

The endpoint returns 200 OK with one result for each input, in the same order:

{
  "data": {
    "results": [
      {
        "status": "created",
        "input": "checkout.example.com",
        "domain": "checkout.example.com",
        "domainId": "1897425263682514945"
      },
      {
        "status": "existing",
        "input": "app.example.com",
        "domain": "app.example.com",
        "domainId": "1897425263682514946"
      },
      {
        "status": "invalid",
        "input": "not a hostname",
        "code": "invalid_domain",
        "message": "Domain is invalid."
      }
    ],
    "totals": {
      "created": 1,
      "existing": 1,
      "invalid": 1
    }
  }
}

The request can contain both successful and invalid results while still returning 200 OK. Inspect every result:

Status	Meaning
created	cside registered the hostname and returned its new domainId
existing	The same team already owns the hostname; the original domainId is returned
invalid	cside did not register the hostname; inspect code and message

Retries are safe for domains that were already created for the same team. They return existing instead of creating a duplicate. A hostname managed by another team returns invalid with domain_already_licensed.

New domains enter managed protection automatically. No separate activation API call is required. Configuration may take a short time to reach the delivery network.

Domain validation codes

An invalid result can include one of these codes:

Code	Meaning
empty_domain	The input is empty
invalid_domain	The hostname is not valid
public_suffix_domain	The input is a public suffix rather than a registrable hostname
internal_domain	The hostname is reserved or not allowed
reserved_ip	DNS resolves the hostname to a reserved IP address
wildcard_conflict	An existing wildcard domain already covers this hostname
subdomain_conflict	An existing domain configuration already includes this subdomain
domain_already_licensed	Another team already manages the hostname
internal_error	cside could not validate or create the domain

Load cside for the team

Use the teamId returned by team creation in the standard cside script URL. Do not substitute a domainId.

<script
  src="https://[your-team-id].csidetm.com/client.js"
  referrerpolicy="origin">
</script>

The page hostname must be registered under the same team ID used in the script URL. A missing registration or team mismatch returns 403. If this happens immediately after registration, retry shortly. Contact cside support if it continues.

Standard monitoring does not require a customer CNAME or traffic rerouting. If your site has a restrictive Content Security Policy, follow the CSP setup guide to allow *.csidetm.com.

Automatic domain onboarding

Automatic domain onboarding is an optional team capability for deployments that load the standard cside bootstrap script. It is disabled by default for new teams. Contact your cside representative if you need it enabled.

When the capability is enabled and an unregistered hostname loads the team-specific /client.js or /script.js bootstrap, cside submits the referring hostname through the same domain validation and registration flow. Keep the standard referrerpolicy="origin" attribute so the page origin is available without exposing its path or query string.

The request that detects the unregistered hostname is not retried. Registration affects a later script request after configuration has propagated. Automatically registered domains appear in the team’s domain inventory like domains registered through the API.

Automatic onboarding does not create teams, and requests to other cside endpoints do not register a hostname. Use the explicit API workflow when you need a result for every domain before deploying the script. Automatic onboarding applies to the standard monitoring script and does not enable Device Intelligence collection.

Delete domains

Use DELETE /v1/domains/ with the domainId values returned by domain registration. Do not send hostnames to this endpoint.

curl --request DELETE \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "1897425263682514945",
      "1897425263682514946"
    ]
  }'

You can send 1 to 100 domain IDs. A successful request returns ordered partial results:

{
  "data": {
    "results": [
      {
        "status": "deleted",
        "domainId": "1897425263682514945",
        "domain": "checkout.example.com"
      },
      {
        "status": "not_found",
        "domainId": "1897425263682514999"
      }
    ],
    "totals": {
      "deleted": 1,
      "not_found": 1
    }
  }
}

Deletion is idempotent. An unknown ID, an already deleted domain, or a domain outside the target team returns not_found without exposing information about another team.

Request-level errors

Request-level failures use this shape:

{
  "error": "insufficient_scope",
  "message": "Token is missing the domains:create scope."
}

HTTP status	Common error codes	Action
400	invalid_request	Check the JSON body, required fields, ID strings, and item limits
401	unauthorized	Check the bearer token and whether all organization tokens were revoked
403	insufficient_scope, enterprise_required, suspension errors	Check token permissions, plan access, and account status
404	team_not_found	Confirm the team ID belongs to the token’s organization
409	team_name_exists	Choose a unique team name or use the existing team
429	rate_limited	Retry with backoff after the current rate-limit window
503	rate_limit_unavailable, domain_deletion_unavailable	Retry later; contact cside support if the error continues

Security checklist

• Generate a separate token for each backend integration
• Grant only the permissions that integration needs
• Store tokens in a server-side secret manager
• Never expose tokens in browser code, URLs, source control, or logs
• Revoke all organization tokens immediately if one is exposed
• Treat returned team and domain IDs as strings

Related documentation

• Interactive API reference
• Adding your domain
• Adding the cside script
• Dashboard settings