Skip to content

REST API

SecObserve is build with an API first approach, every functionality needed to use SecObserve is covered by the REST API.

Authentication

JWT

JWT authentication is used by SecObserve's frontend.
Endpoint /api/authentication/authenticate/
Validity duration for regular users 7 days / 168 hours 1)
Validity duration for superusers 1 day / 24 hours 1)
HTTP header Authorization: JWTtoken

1) Values can be changed by the administrators.

A secret is stored in the database that is used to generate the JWT token. The secret can be reset to a new value with a button in the settings:

Reset JWT secret

After a confirmation dialog, this will invalidate all existing tokens and users have to log in again.

API token

API tokens are used for other integration scenarios, e.g. to call the REST API from a CI/CD pipeline to import observations.
Validity Until revokation
HTTP header Authorization: APITokentoken

API tokens can be created for a product or a user.

Product API token

Create product API token 1

A role (see Roles and permissions) must be selected during creation of a product API token, to determine the permissions of the API token for the product.

Create product API token 2

The API token can be seen only once after it has been created. It must be copied to ensure that it is not lost.

Create product API token 3

Only one API token can be created per product. If it needs to be replaced, it must be revoked first.

Revoke product API token

User API token

API tokens for a user can be created and revoked in the user's page in the SecObserve frontend or with API calls. A token can be seen only once, when it is created. Afterwards there is no way to see that API token again. If it is lost it needs to be revoked and a new one has to be created. Several API tokens can be created per user, each of them has a name and an optional expiration date.

The API token has the same permissions for the same products as the user.
Endpoint to create API token /api/authentication/create_user_api_token/
Endpoint to revoke API token /api/authentication/revoke_user_api_token/

Because an API token is a long lived credential, the user has to prove their identity when a token is created or revoked. There are two ways to do so:

  • Users with a password: The parameters username and password are sent in the body of the request.
  • Users authenticated with OpenID Connect: The id token is sent in the Authorization: Bearertoken header and the parameters username and password are omitted. Users authenticated with OpenID Connect have no password in SecObserve, a recent authentication at the OIDC provider is the proof of identity instead. See OpenID Connect authentication for the details.

The endpoints answer with HTTP status 403 and one of these codes in the body, if the authentication at the OIDC provider is not recent enough or cannot be checked:

Code
oidc_reauthentication_required The authentication is older than the configured maximum authentication age
oidc_auth_time_missing The id token has no auth_time claim, so the age of the authentication cannot be checked

Interactive API documentation

The full documentation of the REST API is available at <BACKEND_URL>/api/oa3/swagger-ui.

Deleting products and product groups

DELETE /api/products/{id}/ and DELETE /api/product_groups/{id}/ require the exact, case- and whitespace-sensitive resource name in the name query parameter. Deletion cascades to dependent data.

DELETE /api/products/42/?name=Example%20Product

The same query parameter is required by the Product Group endpoint. Product Group deletion also permanently deletes all child Products and their dependent data. A successful deletion returns 204 No Content; a missing, invalid, or non-matching name returns 400 Bad Request, a caller without the matching delete permission receives 403 Forbidden, and a remaining restricted cross-resource reference returns 409 Conflict. Confirmed deletion is irreversible.