Accessing Corteza

Corteza separates the back-end business logic and the front-end user interface by defining an API that the clients (web applications and other custom applications) can access.

All operations that can be performed via user interfaces can be performed via an API call (or a series of API calls).

Authentication

Corteza uses bearer JWT tokens when authenticating HTTP requests. To obtain access tokens, you need to define a user and an auth client.

You can use an existing user or create a dedicated user. Make sure that the selected user has sufficient permissions (is a member of appropriate roles).

We recommend you create a dedicated user with only the required roles.

Create a new auth client with the client_credentials grant type. Insert the ID of the selected user under the "Impersonate user" (the user that we mentioned above).

If the user’s ID is not set or is not valid, an Error: "auth client security configuration invalid" error is returned.

Use the following cURL request example to fetch the access token:

curl -X POST $CORTEZA_URL/auth/oauth2/token \
     -d grant_type=client_credentials \
     -d scope=api \
     -u <client id>:<client secret>

An example of the cURL request:

curl -X POST $CORTEZA_URL/auth/oauth2/token \
     -d grant_type=client_credentials \
     -d scope=api \
     -u 229978909641277628:sMVVcYpXE6bOUm6gG0sJGKmDOzEgkYyhvKyrmcU9fGY8M4GhLd90lThZDxUUFLC9

An example response object:

{
  "access_token": "ey...MsLA",
  "expires_in": 7200,
  "refresh_token_expires_in": 0,
  "scope": "api",
  "sub": "229974909641277121",
  "token_type": "Bearer"
}

The above token expires after two hours; make sure to fetch a new one.

Each HTTP request to a protected resource must provide the bearer JWT token in the authorization header. Unauthorized requests yield an error response of { "error": { "message": "Unauthorized" } } (or similar).

JWT tokens should be treated as login credentials as they provide access to the system.

An example cURL with authentication:

curl "$CORTEZA_URL" \
  -H 'accept: application/json, text/plain, */*' \
  -H "authorization: Bearer $JWT";

An example cURL without authentication:

curl "$CORTEZA_URL" \
  -H 'accept: application/json, text/plain, */*';

Table 1. Corteza Low Code endpoints with alternative request authentication:
Endpoint	Other authentication methods
`GET /namespace/{namespaceID}/attachment/{kind}/{attachmentID}/original/{name}`	System generated signature.
`GET /namespace/{namespaceID}/attachment/{kind}/{attachmentID}/preview.{ext}`	System generated signature.

Table 2. Corteza Federation endpoints with alternative request authentication:
Endpoint	Other authentication methods
`POST /nodes/{nodeID}/handshake`	System generated OTT token.

Endpoints

Each Corteza instance ships with a built-in API reference that is accessible on the /docs endpoint of your Corteza API.

Here we cover endpoints used for debugging and maintenance. Refer to the built-in API reference for the complete list of available service endpoints. Here is the API reference for our community instance.

If you are using a different sub-domain for your API (two separate Docker containers for web app and API), the URL should look something like https://api.$BASE_URL/docs.

If you are using the same domain for your API (a single Docker container for web app and API), the URL should look something like https://$BASE_URL/API/docs.

In addition to the API reference mentioned above, these are the system-level endpoints that need to be explicitly enabled. They can be enabled for development/debugging but should be disabled when running in production.

Table 3. System-level endpoints:
Option	Endpoints
`HTTP_ENABLE_DEBUG_ROUTE`	`/__profiler` provides server runtime profiling data in the format expected by the pprof visualization tool. `/__routes` provides a list of all registered routes. `/__eventbus` presents a list of all registered automation script triggers. `/__corredor` presents a list of all registered automation scripts.
`HTTP_ENABLE_VERSION_ROUTE`	`/version` shows the build time and the Corteza version.
`HTTP_ENABLE_HEALTHCHECK_ROUTE`	`/healthcheck` performs and displays the system health check.

Response data format

Corteza implements three different response formats, based on what we are trying to do and based on the status.

Error responses use the status code 200 OK, instead of the standard 4xx/5xx — legacy reasons. Our API clients cover this case and throw correct errors.

Working with single items

When working with single items, the item (or its status) is provided in the response object.

Example:

{
  "response": {...}
}

Working with multiple items

When working with multiple items, the list of items is provided in the response array along with the filter object.

Example:

{
  "response": {
    "filter": {...},
    "set": [...]
  }
}

The structure of the filter property differs based on the resource. In general, it specifies what filters were applied to the responding set.

Encountered an error

When an error occurs, the error message is provided under the error.message property.

Example:

{
  "error": {
    "message": "..."
  }
}

When you enable error tracing via the HTTP_ERROR_TRACING environment variable, the additional error contexts are provided in the stack and wrap properties. This can be useful for debugging but should be turned off in production.

Example:

{
  "error": {
    "message": "...",
    "stack": [...],
    "wrap": {...}
  }
}