Authentication

The VION Cloud API uses Keycloak as its identity provider with OpenID Connect (OIDC). All API calls require a valid Bearer token.

Getting an Access Token

Interactive (Authorization Code Flow)

For user-facing applications, use the Authorization Code Flow with PKCE:

1. Redirect the user to the Keycloak authorization endpoint
2. User authenticates and grants consent
3. Exchange the authorization code for tokens

Authorization URL: https://auth.<env>.ecocoa.ch/realms/vion/protocol/openid-connect/auth
Token URL:         https://auth.<env>.ecocoa.ch/realms/vion/protocol/openid-connect/token

Parameter	Value
client_id	Your registered client ID
scope	openid user_impersonation
response_type	code
code_challenge_method	S256 (PKCE required)

TIP

The easiest way to explore the API interactively is through the Scalar API Reference, which has built-in OAuth authentication.

Machine-to-Machine (Client Credentials Flow)

For CI/CD pipelines and service integrations, use the Client Credentials Flow:

curl -X POST https://auth.<env>.ecocoa.ch/realms/vion/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-client-secret>"

Response:

{
  "access_token": "eyJhbGci...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Token Refresh

Access tokens are short-lived. Use the refresh token to get a new one without re-authenticating:

curl -X POST https://auth.<env>.ecocoa.ch/realms/vion/protocol/openid-connect/token \
  -d "grant_type=refresh_token" \
  -d "client_id=<your-client-id>" \
  -d "refresh_token=<your-refresh-token>"

Using the Token

Include the access token in the Authorization header:

curl -H "Authorization: Bearer <access-token>" \
  https://cloudapi.<env>.ecocoa.ch/Me

API URL Structure

The API uses a scoped URL pattern reflecting the multi-tenancy hierarchy:

Level	URL Pattern	Example
Common	/<controller>	GET /Me
Integrator	/Integrator/{integratorId}/<controller>	POST /Integrator/{id}/LogicBlockLibraryVersions
Tenant	/Tenant/{tenantId}/<controller>	GET /Tenant/{id}/Services

Most operational endpoints (services, properties, projects) are at the Tenant level.

Environments

Environment	Auth URL	API URL
Test	auth.test.ecocoa.ch	cloudapi.test.ecocoa.ch
Staging	auth.staging.ecocoa.ch	cloudapi.staging.ecocoa.ch
Production	auth.ecocoa.ch	cloudapi.ecocoa.ch