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.

Corteza is API-centric, meaning that everything can be done via an API endpoint.

Authentication

Corteza uses bearer JWT tokens when authenticating HTTP requests.

JWT tokens grant access to your system, so treat them as login credentials.

Obtaining access tokens

Before you can obtain the access token, you need to define an auth client, and a system user. You can use an existing user (such as yourself), or create a dedicated user.

Make sure that the system user has sufficient roles to be able to access resources which you wish to access.

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).

Make sure that you are using Corteza 2021.3.4 or later.

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.

Using access tokens

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"
  }
}

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.

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.

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

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": {...}
  }
}