Skip to main content

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

JSON Web Token

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 a number and it should be displayed in your portal API status page)

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

auth.png

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

AuthFail.png

 

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

AuthHeader.png

 

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.

RefreshToken.png

 

Two factor authentication

If your account has 2FA enabled, you should get a response similar to the one bellow:

login_with_2fa_response_2.png

On the field twoFactorAuthProviders, you can see your available providers. Unfortunately, the API 2FA only works when using the email provider. 

Then you will need to do a POST to the endpoint SendTwoFactorAuthCode, like the one bellow:

2fa.png

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 field to the Authenticate payload and paste your email or google code:

 

API Keys - Pentester Portal

API Key authentication can be used from the Pentester Portal. An API key is a unique identifier and authentication token that provides secure access to an API.

To manage them, go Administration -> Integrations -> API.

When generating a new key, you can give it a descriptive name. Make sure you copy the key when creating, you won't be able to see it again afterwards.

To authenticate your requests using the API key, include it in the HTTP header of each request:

curl -X GET "https://{your_portal_name}.cyver.io/.." \  -H "X-API-Key: your_api_key_here"
 

 

API Keys - Client Portal

API Key authentication is also available on Cyver on the Client Portal. An API key is a unique identifier and authentication token that provides secure access to an API.

To manage them, the Client (manager) goes to Settings -> Integrations -> API.

When generating a new key, you can give it a descriptive name. Make sure you copy the key when creating, you won't be able to see it again afterwards.

To authenticate your requests using the API key, follow the instructions explained one section above.

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

 

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. - V2 currently doesn't have support for Clients API.

At a smaller level, the API is divided in /pentests, /findings and /clients 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.

 

Was this article helpful?