Working with the API

The Cyver Core API is a REST API that uses standard HTTP response codes, JSON-encoded responses and accepts form-encoded request bodies.

Authentication

The Cyver Core API uses JSON Web Tokens (Bearer) for authentication. This security token is necessary for all the available API requests. All requests must be made over HTTPS. API requests without authentication will fail.

To retrieve this token, you first need to follow these steps and activate the Cyver Core API.

The following steps will be demonstrated using Postman, but you can also do it without it.

In order to authenticate and retrieve a valid token, create a POST call to

https://{your_portal_name}.cyver.io/api/TokenAuth/Authenticate

Add a JSON object with usernameOrEmailAddress and password properties.

Fill the following headers

• Content-Type: application/json
• Content-Length
• Host
• Abp.TenantId (this is an integer that should be in your portal API status page)

And if the request is valid, your token will be on the accessToken field of the response.

If not, you will get a description of what might be wrong with the request.

After this, you just need to add the Authorization header to all requests.

The accessToken has a duration of 1 day. After that, you can request another token by creating a POST call to the following endpoint:

https://{your_portal_name}.cyver.io/api/TokenAuth/RefreshToken?refreshToken={your_refresh_token}

This will return a new accessToken, valid for another 24 hours.

Two factor authentication

If your account has 2FA enabled, you have to 2 options depending on the 2FA provider. In both scenarios, you should get a response similar to the one bellow:

On the field twoFactorAuthProviders, you can see both options. If you are using Email, you will need to do a POST to the endpoint SendTwoFactorAuthCode, like the one bellow:

After this, you should get a 2FA code on your email account.

Now, you are able to get an access token, by adding the twoFactorVerificationCode to the Authenticate payload and paste your email or google code:

Response format

All API responses follows the following format:

{
  "success": true,
  "result": {
    "personId": 42
  },
  "error": null,
  "targetUrl": null,
  "unAuthorizedRequest": false,
  "__abp": true
}

• success: A boolean value (true or false) that indicates the success status of the operation.
• result: The actual return value of the controller action. It's valid if the request was a success and if the server sent a return value.
• error: If success is false, this field is an object that contains the message and details fields.
• targetUrl: This provides a way for the server to redirect the client to another url if needed.
• unAuthorizedRequest: This provides a method for the server to inform the client that this operation is not authorized or the user is not authenticated.
• __abp: Framework specific, you can ignore this field.

Swagger

We also offer a Swagger UI documentation for all endpoints. It's available on https://{your_portal_name}/api (E.g.: https://test.cyver.io/api). You must be logged in to access the page.

This documentation contains a brief description of each endpoint, parameters and response model schemas. You can also test the API directly from here (don't need to do authentication first because you are already logged in).

It is organized by PentesterAPI and ClientAPI controllers. Pentesters cannot use the ClientAPI and Clients cannot use PentesterAPI.

Clients API scope is smaller than Pentester's. Basically mimics the same operations each one can do on the portal.

At a smaller level, the API is divided in /pentests, /findings and /assets as they are the most important concepts on our platform.

Additionally we also offer a sample Postman file that you can import and use it to test the API. It is available for download at the bottom of the article.