Guides (1.0)

This guide will walk you through a basic tutorial to retrieve the vulnerabilities that you either received as an enterprise or submitted as a hacker.

Read on to learn more about:

• Creating your API keys
• Getting an access token
• Making your first API call

Using Basic Authentication to access Yogosha API

Yogosha API uses the Basic HTTP Authentication for authentication and authorization.

To get your API key, you must create an app by following the steps below:

1. In your personal Settings, go the API Keys page.
2. Click on the New API Key button.
3. Choose a relevant name for your application.
4. Choose the scopes you need for your application from the available scopes.
5. Click on the Save button.
6. Your API keys (access_token) should be displayed. Copy and safely store them as they will be displayed only once. You'll need these when making future API calls.

Removal of API keys

If your API keys get compromised, they can be revoked anytime.

Before being able to make your first API call, you must encode in base64 your username and your access token in this format: username:access_token

echo -n "username:access_token" | base64

dXNlcm5hbWU6YWNjZXNzX3Rva2Vu

Finally, you can use the string encoded in base64 (username:access_token) to make authenticated API calls by setting it as "Basic" token in the Authorization header :

curl --request GET \
  --url https://api.yogosha.com/api/reports \
  --header 'authorization: Basic ENCODED_ACCESS_TOKEN'

method: get
url: 'https://api.yogosha.com/api/reports'
headers:
  Authorization: Basic YOUR_ACCESS_TOKEN

The Yogosha REST API use the standard HTTP status code.

In case of error, response may contained a body with more information on the error to help you. The response will contain 2 fields, an explicit message and a error code. Example:

    {
      "code": 100,
      "message": "Invalid sorting parameter - The name of the property and the order must be separated by a dot (i.e. \"createdAt.desc\")."
    }

Find a full list of possible codes below.

Validation

• 10 - Unknown Resource ID

  The resource with given ID could not be found. It happens when using the id of resource in a payload and that ID doesn't exist.

Sorting

• 100 - Invalid Sorting Parameter

  The name of the property and the order must be separated by a dot (i.e. "createdAt.desc").

• 101 - Invalid Sorting Order

  Order value must be either asc or desc.

• 102 - Invalid Sorting Property

  The requested property is not available on the endpoint.

Pagination

• 110 - Invalid Page Number

  Pagination starts at page 1. The page parameters must be greater than or equal to 1.

• 111 - Max Item Per Page

  A paginated response can include up to 100 items.

Embeddables

• 120 - Invalid Requested Embeddable

  The requested embeddable "%s" is not available.

The Yogosha REST API uses pagination to improve performance. Pagination is enforced for operations that could return a large collection of items. When you make a request to a paginated resource, the response wraps the returned array of values in a JSON object with paging metadata. For example:

{
  "data": [],
  "pagination": {
    "total": 2,
    "totalPages": 1,
    "perPage": 20,
    "page": 1
  }
}

• data will contain the resources
• pagination.total contain number of resources in the data set
• pagination.totalPages contain number of page in the data set
• pagination.perPage contain number of resources per page
• pagination.page contain index of current page

The Yogosha REST API uses resource embeddable, which means that some parts of a resource are not returned unless specified in the request. This simplifies responses and minimizes network traffic.

To embed part of a resource in a request, use the embed query parameter and specify the object(s) to be embeded. If you need to embed multiple objects, use a comma-separated list.

For example, the following request will add program object information and additional content on the report with id 1OI6J5xY5kMDbwD3PWA9OD:

GET /api/reports/1OI6J5xY5kMDbwD3PWA9OD?embed=program,content

For now the api doesn't support nested object with embed function.

Some operations support sorting the elements of a response by a field. Check the documentation for the operation to confirm whether sorting of a response is supported and which fields can be used. When sorting is used, direction of sort must be given, ther is not default. Example:

• ?sortBy=title.asc will sort the result by title using ascendant direction
• ?sortBy=title.desc will sort the result by title using descendant direction

API supports sorting on multiple fields in the same request, using coma separated list. Be aware direction must be declared for each field. Example:

• ?sortBy=type.asc,createdAt.desc will sort the result by type using ascendant direction and createdAt using descendant direction

Manage and retrieve information about the digital assets monitored within your attack surface. This includes domains, IPs, services, and other exposed resources.

Create and manage test accounts used for security assessments, validations, and attack surface verifications.

Programs

Access, manage, and export finalized vulnerability reports for review or sharing with stakeholders.