Frequently Asked Questions

Requesting Client Credentials

Client credentials (client_id and client_secret) are issued by Cadasto after we provision an environment for you. This section explains what to provide when requesting credentials and includes a request template you can copy.

Why you need credentials

Client credentials enable server-to-server integrations using the OAuth 2.0 Client Credentials flow.
Credentials are issued per environment (development, acceptation, production) and must be treated as secrets.

What to provide

Information	Description
Application name	A friendly name used for identification
Environment(s)	`development`, `acceptation`, `production`
Redirect URIs	Required for interactive flows (PKCE). Leave empty for pure machine-to-machine (Client Credentials)
Allowed origins (CORS)	Required if your application runs in a browser
Scopes	Minimum set required, e.g. `api.read`, `api.write`
Contact	Name, email, and team alias of the technical owner
Description	What the integration does and expected usage patterns

Request template

Copy and adapt for your email or support ticket:

Subject: Request: Cadasto API client credentials for <application-name>

Application name: <your-app-name>
Environment: development | acceptation | production
Redirect URIs: <https://app.example.com/callback> (optional; required for interactive flows)
Allowed origins (CORS): <https://app.example.com> (optional)
Requested scopes: api.read api.write
Contact: Jane Doe <jane@example.com>
Description: <Short description of what the integration does and why it needs access>

What you will receive

client_id — public identifier for your application
client_secret — confidential secret; store it securely (secret manager, environment variables, or vault)
Optional: additional metadata about allowed scopes or token lifetime

Security and lifecycle

Store secrets securely. Never check client_secret into source control. Use a secret manager, environment variables, or vault solution.
Rotate on compromise. If a secret is exposed, rotate it immediately. Follow your organization's rotation schedule.
Per-environment isolation. Credentials for development, acceptation, and production are separate. Treat each set independently.

After you receive credentials

Follow the Authentication guide to obtain an access token using the Client Credentials flow.
Follow the Quick Start to create your first EHR and commit data.

Need help? Contact Cadasto support with the information above and we'll get you set up.

Template Versioning

Cadasto supports multiple versions of the same template. Each published version receives a unique identifier following the pattern:

{template_id}::{uid}

For example:

Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747

Example.v1 — the template identifier (including its semantic version)
c7ec861c-c413-39ff-9965-a198ebf44747 — a unique UUID assigned to this specific published version

Why this matters

You can upload a new version of a template without removing the previous one.
Existing compositions remain valid against the template version they were committed with.
When committing a composition, you can target a specific template version by using the full {template_id}::{uid} identifier.
When listing templates via GET /definition/template/adl1.4, the response includes all published versions with their unique identifiers.

Working with template versions

Upload a new version of an existing template:

POST /definition/template/adl1.4
Content-Type: application/xml
Authorization: Bearer <token>

The server assigns a new UUID to the uploaded version. If a template with the same template_id already exists, both versions remain available.

Retrieve a specific version:

GET /definition/template/adl1.4/Example.v1::c7ec861c-c413-39ff-9965-a198ebf44747
Authorization: Bearer <token>

AQL - Archetype Query Language