Authentication and scope

Set the integration key scope and distinguish the external API from application sessions.

Last updated: 10 November 2026

Choose the integration identity first

Use a user-bound access key for external integrations. v1 endpoints expect Authorization: Bearer ERISIM_ANAHTARI; they do not accept a session cookie. Create a key under Access keys in the user menu. Follow Quick start for your first call.

Do not continue with the same secret if its owner becomes inactive, organisation access closes, the key expires or is revoked. Current account permissions apply on every request. A Viewer account cannot receive write scope.

Store and rotate the key

The secret is shown only in the creation response. Store it in secure server configuration; keep it out of URLs, source code, browser bundles and logs. To change scope or rotate a secret, create a new key, check that the integration works with it and remove the old key with Cancel.

If a secret is exposed, revoke the key and generate a new secret; do not reuse the same secret under another name. Review the projects it could access and relevant organisational records. Access keys describes management endpoints and the lifecycle.

Application sessions

The cookie-authenticated endpoints below form the browser application's session contract. Key creation and webhook management require this session. Do not assume all application endpoints accept keys instead of using v1 for external read/write integrations.

Starting a browser session

POST /api/auth/login takes username and password in a JSON body. username may be a username or registered email address. A successful response has this form:

{"ok": true}

The server sets a sosogis_oturum cookie with HttpOnly, Secure, SameSite=Lax and Path=/. A session lasts 30 days from sign-in and is not extended on every request. The Secure attribute requires HTTPS. Subsequent requests carry the same session cookie; the response body does not provide a bearer token.

Invalid credentials return 401. For request-limit rejections, handle 429 and any Retry-After header. Sessions cannot be used when the user or organisation is inactive.

Browser client

The application makes its own API requests on the same origin. To read user information with an existing session:

const yanit = await fetch('/api/auth/me', {
  credentials: 'same-origin',
  cache: 'no-store'
});
if (!yanit.ok) throw new Error(`HTTP ${yanit.status}`);
const kullanici = await yanit.json();

JSON writes must use Content-Type: application/json. For file uploads, create FormData and let the browser generate the Content-Type header with its boundary.

CSRF and integration boundaries

The current application API has no separate CSRF-token generation or X-CSRF-Token validation workflow. It uses a SameSite=Lax session cookie and a same-origin client. This does not mean direct browser integrations from other origins are ready; no general CORS configuration is defined.

Users can create an access key for external integration. Keys are used with /api/v1 and OGC endpoints; they do not remove the session requirement of the cookie-authenticated application endpoints on this page. Central administration service identity is separate from a user-bound access key.

Session endpoints

The new password must be 8–200 characters long. Changing it closes other sessions but preserves the session making the change. Keep credentials out of application source code and integration logs.

Permission checks

Role values are superadmin, admin, editor and viewer. The API display name for viewer corresponds to Viewer. Write permission alone is insufficient; module, organisation, project membership, region and licence requirements must also be met.

A project outside the organisation returns 404 even when it exists. A lost session may return 401; a write rejected by permissions or licensing may return 403. See Error codes.