Authentication

Draft.

Method

Machine-to-machine access to the public API uses the OAuth2 client credentials flow. You obtain a short-lived, scoped access token and send it on every request as Authorization: Bearer <token>.

• No long-lived static API keys are issued.
• Tokens are issued by our identity provider (Keycloak); the Corendis application only validates them.
• The browser cookie (web application session) is not accepted on the public API.

How an integration client is set up

You do not create integration clients yourself:

1. You send a request to BilgiTek (client name, purpose, which data it needs).
2. BilgiTek staff define the client in the platform management panel, bound to your company (tenant), and grant its permissions (which operations and, where needed, which legal entities).
3. You receive a client_id and a credential. A client_secret is shown only once, so you must store it. private_key_jwt is supported as an alternative.

Key points:

• A client is bound to exactly one tenant. The tenant is determined from the client identity in the token; adding a tenant identifier to your request has no effect.

• A client's permissions are separate from the application's user roles. Even your company's administrator cannot give a client permissions through roles; only BilgiTek manages them.

• When a credential is rotated, the old and new credentials are valid together for a transition period.

• Integrations cannot be used to bypass user seats; each client uses an integration seat.

• Clients on behalf of an external organization (for example a dealer or partner company) are not supported yet.

What determines effective permission?

For a request to succeed, all three must allow it:

1. The token's scope,
2. The permissions BilgiTek granted to the client,
3. Your company's license (module and integration seat).

If any is missing, the request is rejected with 403. The type field tells you which one (see Errors).

Scope names

Example (placeholder)

POST <TOKEN_URL>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=<SCOPE>

Security recommendations

• Never put client_secret in source code, repositories or logs.
• Reuse a token until it expires; do not request a new one for every call.
• Ask BilgiTek to disable clients you no longer use.