Authentication

All Ditio API endpoints require authentication. The API uses OAuth 2.0 client credentials: you exchange a client_id and client_secret for a short-lived bearer token, and send that token with every request.

Environments

Ditio has two environments. Credentials are per-environment — a client created in production does not work in test, and vice versa.

Test environment

The test environment is a safe sandbox. It is synced from production periodically, so anything you create directly in test will eventually be overwritten. Build and verify your integration here first.

⚠️ Production environment

Production holds live customer data. Writes are real: created users get invited, created projects appear for field workers. Only point your integration at production once it has been verified in test.

All code samples in this documentation use environment variables so you can switch environments in one place — and they default to test:

# Test (default for all examples)
export DITIO_API_BASE="https://core-api.ditio.dev/core"
export DITIO_REPORTING_BASE="https://core-api.ditio.dev/reporting"
export DITIO_IDENTITY_BASE="https://identity.ditio.dev"

# Production — only after verifying in test
# export DITIO_API_BASE="https://core-api.ditio.app/core"
# export DITIO_REPORTING_BASE="https://core-api.ditio.app/reporting"
# export DITIO_IDENTITY_BASE="https://identity.ditio.app"

Creating API credentials

Any Ditio administrator can create API credentials self-service:

1. Log in to Ditio Web.

2. Go to Company Setup (Oppsett) → Integration.

3. Click Create new API client and give it a descriptive name (e.g. “ERP Integration”, “Power BI”).

4. The system generates a client_id and client_secret.

Caution

Save the client_secret immediately — it is shown only once and cannot be retrieved later. If you lose it, create a new client.

Create separate clients for separate use cases so they can be disabled or deleted independently. Disabling a client immediately revokes its access.

Obtaining a Token

Exchange your credentials for a bearer token at the identity server:

curl -X POST "$DITIO_IDENTITY_BASE/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=ditioapiv3"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 1800,
  "token_type": "Bearer",
  "scope": "ditioapiv3"
}

The scope you request decides which API the token works against, so it has to match the endpoint you are calling — see Which scope for which host below. ditioapiv3 covers the Core and Integration API; the Data Extraction API needs reportingapiv1 instead.

Scopes

Scope	Grants access to
ditioapiv3	Core + Integration API — use this for most integrations
masstransportapiv1	Mass Transport API (machine integration)
reportingapiv1	Reporting / Data Extraction API

If your integration calls more than one of these APIs, you can request several scopes in one token by separating them with a space:

  -d "scope=ditioapiv3 reportingapiv1"

Only request scopes your client is granted

A multi-scope request is all-or-nothing. If your client isn’t granted one of the scopes you ask for, the identity server rejects the whole request with 400 Bad Request / invalid_scope and issues no token at all — it does not quietly hand back the scopes you are allowed. Many clients are granted ditioapiv3 only, so add a second scope to your token request only once you know the client has it.

Which scope for which host

Each base URL requires its own scope. A token is accepted only if it carries the scope for the API you are calling — a token requested with ditioapiv3 alone is not accepted by $DITIO_REPORTING_BASE, even though both live on the same hostname. A token requested with several scopes carries all of them and is accepted by every host whose scope it holds.

Base URL	Scope required	Documented in
$DITIO_API_BASE — core-api.ditio.app/core	ditioapiv3	Integration API
$DITIO_REPORTING_BASE — core-api.ditio.app/reporting	reportingapiv1	Data Extraction API
$DITIO_MASSTRANSPORT_BASE — provided by your Ditio contact	masstransportapiv1	Machine Integration

Scope lives on the token, not on the request

Scope is decided once, when you fetch the token. There is no Scope request header — sending one has no effect. If a token was issued for the wrong scope, the API rejects it with 401 Unauthorized (not 403), and refreshing the token will not help, because the new token has the same wrong scope. See Error Handling.

reportingapiv1 isn’t listed in the admin UI

The API client screen in Ditio Web doesn’t offer reportingapiv1 as its own option, and a large share of clients are granted ditioapiv3 only. If your token request fails with 400 / invalid_scope, that scope isn’t on your client; contact support@ditio.no to have it enabled.

Using the Token

Include the access token in the Authorization header of every API request:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "$DITIO_API_BASE/api/v4/integration/projects"

Scope is never read from a request header — it comes from the token.

Token Expiry

Tokens are short-lived — about 30 minutes by default (configurable per client, up to 24 hours). Read expires_in from the token response, cache the token, and refresh it shortly before it lapses. Your integration should also handle 401 Unauthorized responses by requesting a new token — but only retry once. If the retry also returns 401, the token is being rejected for something other than expiry and retrying will loop forever; read the WWW-Authenticate header to see which cause it is, per Error Handling. Never request a fresh token per API call.

// Cache the token; only fetch a new one shortly before it expires.
private static string _token;
private static DateTime _tokenExpiresUtc = DateTime.MinValue;

async Task<string> GetTokenAsync(HttpClient http)
{
    // Refresh ~1 minute early so a token never expires mid-request.
    if (_token is not null && DateTime.UtcNow < _tokenExpiresUtc.AddMinutes(-1))
        return _token;

    var identityBase = Environment.GetEnvironmentVariable("DITIO_IDENTITY_BASE")
                       ?? "https://identity.ditio.dev";
    var response = await http.PostAsync(
        $"{identityBase}/connect/token",
        new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["grant_type"]    = "client_credentials",
            ["client_id"]     = clientId,
            ["client_secret"] = clientSecret,
            // Must match the API being called — see "Which scope for which host".
            ["scope"]         = "ditioapiv3",
        }));
    response.EnsureSuccessStatusCode();

    var token = await response.Content.ReadFromJsonAsync<TokenResponse>();
    _token = token!.access_token;
    _tokenExpiresUtc = DateTime.UtcNow.AddSeconds(token.expires_in);
    return _token;
}

private record TokenResponse(string access_token, int expires_in, string token_type);

Long-lived tokens from the UI

If you can’t run the token flow (e.g. a BI tool that only accepts a static token), an administrator can generate a longer-lived token directly in the Ditio Web UI on the integration page (these are audited). Each API client can be disabled or deleted at any time from the same page, immediately revoking access.

Security Best Practices

• Never expose your Client Secret in client-side code or version control
• Store credentials in environment variables or a secrets manager
• Rotate your Client Secret periodically
• Use the minimum required scopes for your integration
• Implement token caching to avoid unnecessary token requests

Note

Need help configuring API access? Contact support@ditio.no.