Fortinet black logo

API Guide

Overview

Copy Link
Copy Doc ID 2432516e-f2c8-11ec-bb32-fa163e15d75b:846127
Download PDF

Overview

The FortiSOAR™ application uses a Representational State Transfer (RESTful) API with a Service Oriented Architecture (SOA) to allow for scalability, flexibility, and ease of use. The characteristics of this design include:

  • Simplicity of interface
  • Scalability, especially when combined within the SOA microservices concepts
  • Maintainability, while the application code may change underneath the API, the API definition may remain in place
  • Performance, component interactions dominate the user-perceived performance and efficiency

The API gives you access to the primary data available to the core system, which are also consumed by the Angular.js client for front end interaction.

FortiSOAR uses the Hydra Specification for implementing the APIs.

Note

While direct access to the module data models and endpoints is provided, we recommend that you consider the Playbooks system as the primary method for working to get data input and output from the FortiSOAR platform. The Playbook system makes development simpler, easier, and more flexible for both ingest and export of data via RESTful methods without requiring debugging or maintenance when new releases are available. However, there may be cases where the Playbooks system does not allow for the required functionality, and custom development on the direct API is needed.

Concepts

JSON-LD

The API uses the JSON for Linking Data (JSON-LD) format to present information. JSON-LD empowers humans and machines to read and write across the core API without pre-existing knowledge of the API structure, other than the root API endpoint. JSON-LD uses embedded links to determine the Context of the API endpoints quickly and easily in a human-readable format.

Tooltip

Example:
API endpoints for "@context": "/api/3/contexts/" and "@id": "/api/3/" are standard pieces of the JSON-LD format.

Hydra Vocab

Additionally, the JSON-LD structure is combined with the Hydra API definition, which applies a standard Core Vocabulary to all data within the API. The Hydra definition is a combination of the Core Vocabulary and the JSON-LD structure to completely define the entirety of the API within itself, making the API standardized and discoverable at the same time.

Note

Any API information described as "@vocab" is a part of the core Hydra definition.

A full list of all of the endpoints and the context around them can be found at /api/3/apidoc.

UUIDs

Universally unique identifiers (UUIDs) are used throughout the system to ensure all records have a unique identifier. The canonical displayed versions are 36 characters using hexadecimal text with inserted hyphen characters in the following format: 123e4567-e89b-12d3-a456-426655440000

When creating new records directly in the API, you may optionally include a generated UUID if you wish to retain that UUID in an external system for reference. This must be a differentiated UUID from any other record in the system, or it will fail.

If you do not include a UUID during a POST, a UUID will be generated for you. This is the recommended method as the response for the POST will contain the IRI with included UUID that you may retrieve and save.

IRIs

All foreign key references use International Resource Identifiers (IRIs) to link records within the system. The format for this is essentially identical to a URI, forming a relative link within the application, though there are differences in the formats. The identifier uses a UUID associated with the record appended to the record location from the API root.

/api/3/alerts/{uuid}

IRIs will be seen in the API typically at the top of a record using the key "@id".

Tooltip

The IRI is automatically generated when inserting the record and is not intended to be used during any POST activities. POST activities should use the "uuid": identifier with a plain 36-character UUID.

Organization

The REST API is organized around the core Modules defined within the platform. Note that most Modules are defined on a 1:1 basis with a database table, though this is not always the case. The root API may be found at https://FortiSOAR_ROOT.URL/api/3, but can only be accessed with the proper authentication. See the Authentication API section in the API Methods chapter for more information.

All Modules and models are made available in the core API, Modules representing a specific data table accessible within the UI. New Modules may be added via the Module Editor in the Administration menu, and every new Module will add a new API endpoint for accessing the records within that Module.

Authentication

Authentication methods for using the API are available via two methods:

  1. Hash-based message authentication code (HMAC) - this method involves computing a specific cryptographic hash via a cryptographic key within the parameters specified from FortiSOAR. This is the required method for permanent API access. See the HMAC Authentication section for more details.
    Note: For HMAC authentication the timestamp must be in UTC format.
  2. Token-based authentication - this method is a temporary access mechanism by using a SHA-256 token, available within the browser resources of the UI. This token expires on a periodic basis and must be refreshed, however, it is useful for temporary access when doing specific API actions during development where generating an HMAC key is not possible, e.g., REST clients and CURL methods.
    The token must be placed in the Header with the Authorization key and the format for identifying the user a Bearer %token%

FortiSOAR utilizes a sessionless security model, meaning the server does not track individual user sessions as objects. Users must be authenticated with a unique token that has a limited lifespan, typically configured at 30 minutes though that may be adjusted. For more information, see the Authentication API section in the API Methods chapter.

Using the HMAC method does not require a session because each message is individually signed with the cryptographic key, but this must be computed, and the server clocks must be in sync for proper operation.

Note

Basic authentication and No authentication webhooks are allowed in the context of the Custom API Endpoint for Playbooks. This is purposeful to reduce the overall risk profile of allowing for less secure methods on the core API.

Authorization

Every API action is reviewed against user authorization privileges. These are determined by your Team membership and Role assignment as described in the "Administration Guide.

Tooltip

We recommend that you always use a limited privilege set scoped to the desired operations to ensure both security and guard against potential data loss due to accidental actions.

Operation

Exercising the API is possible via any valid REST client, such as Postman, or using CURL combined with a user token. All valid CRUD operations allowed via your user privileges may be invoked, but not all endpoints support all HTTP methods.

Supported HTTP Methods

  • GET [Read]
  • POST [Create]
  • PUT [Update]
  • DELETE [Delete]

URI Encoding

The most common format for traversing the API involves using the Module names in the following format.

/api/3/{module name}

An example endpoint for Alerts is as follows:

/api/3/alerts

The body response will include a list of the Alert records found within the database.

{
    "@context": "/api/3/contexts/Alert",
    "@id": "/api/3/alerts",
    "@type": "hydra:PagedCollection",
    "hydra:nextPage": "/api/3/alerts?%24page=2",
    "hydra:totalItems": 1,
    "hydra:itemsPerPage": 30,
    "hydra:firstPage": "/api/3/alerts",
    "hydra:lastPage": "/api/3/alerts?%24page=2",
    "hydra:member": [
        {
        "@id": "/api/3/alerts/028b37fa-bb35-4e3b-8afb-a3274a8cb343",
        "@type": "Alert",
        "name": "Malicious Attachment - Malware.Binary.Vbs",
        "sourceId": null,
        "source": "FireEye EX - Email MPS",
        "origin": "",
        "dueDate": null,
        "description": null,
        "type": null,
        "severity": null,
        "status": null,
        "assignedTo": null,
        "createUser": {
        "@id": "/api/3/appliances/432ba9fe-0955-4379-9177-68b0d87e8caf",
        "@type": "Appliance",
        "name": "Workflow",
        "userId": "7c23b46e-5b84-47c0-8f7f-fe0498156c81",
        "createUser": null,
        "createDate": null,
        "modifyUser": "/api/3/people/bcb46d5a-0ad8-4480-ac68-9ebc28502a30",
        "modifyDate": 1457479171,
        "id": 502,
        "@settings": "/api/3/user_settings/432ba9fe-0955-4379-9177-68b0d87e8caf"
        }]
    "hydra:search": {
    "@type": "hydra:IriTemplate",
    "hydra:template": "/api/3/alerts{?}",
    "hydra:variableRepresentation": "BasicRepresentation",
    "hydra:mapping": []
    }
}

Syntax

FortiSOAR uses the CamelCase format for all data labels, e.g., keys for the key-value pairs in the JSON structure. CamelCase is the practice of writing a compound word or phrase structures where the first letter of the first word is lowercase and subsequent first letters of words following are capitalized.

Tooltip

We recommend you also use CamelCase format during your development to ensure consistency and readability.

Examples

"hydra:variableRepresentation"
"sourceId"
"dueDate"

Overview

The FortiSOAR™ application uses a Representational State Transfer (RESTful) API with a Service Oriented Architecture (SOA) to allow for scalability, flexibility, and ease of use. The characteristics of this design include:

  • Simplicity of interface
  • Scalability, especially when combined within the SOA microservices concepts
  • Maintainability, while the application code may change underneath the API, the API definition may remain in place
  • Performance, component interactions dominate the user-perceived performance and efficiency

The API gives you access to the primary data available to the core system, which are also consumed by the Angular.js client for front end interaction.

FortiSOAR uses the Hydra Specification for implementing the APIs.

Note

While direct access to the module data models and endpoints is provided, we recommend that you consider the Playbooks system as the primary method for working to get data input and output from the FortiSOAR platform. The Playbook system makes development simpler, easier, and more flexible for both ingest and export of data via RESTful methods without requiring debugging or maintenance when new releases are available. However, there may be cases where the Playbooks system does not allow for the required functionality, and custom development on the direct API is needed.

Concepts

JSON-LD

The API uses the JSON for Linking Data (JSON-LD) format to present information. JSON-LD empowers humans and machines to read and write across the core API without pre-existing knowledge of the API structure, other than the root API endpoint. JSON-LD uses embedded links to determine the Context of the API endpoints quickly and easily in a human-readable format.

Tooltip

Example:
API endpoints for "@context": "/api/3/contexts/" and "@id": "/api/3/" are standard pieces of the JSON-LD format.

Hydra Vocab

Additionally, the JSON-LD structure is combined with the Hydra API definition, which applies a standard Core Vocabulary to all data within the API. The Hydra definition is a combination of the Core Vocabulary and the JSON-LD structure to completely define the entirety of the API within itself, making the API standardized and discoverable at the same time.

Note

Any API information described as "@vocab" is a part of the core Hydra definition.

A full list of all of the endpoints and the context around them can be found at /api/3/apidoc.

UUIDs

Universally unique identifiers (UUIDs) are used throughout the system to ensure all records have a unique identifier. The canonical displayed versions are 36 characters using hexadecimal text with inserted hyphen characters in the following format: 123e4567-e89b-12d3-a456-426655440000

When creating new records directly in the API, you may optionally include a generated UUID if you wish to retain that UUID in an external system for reference. This must be a differentiated UUID from any other record in the system, or it will fail.

If you do not include a UUID during a POST, a UUID will be generated for you. This is the recommended method as the response for the POST will contain the IRI with included UUID that you may retrieve and save.

IRIs

All foreign key references use International Resource Identifiers (IRIs) to link records within the system. The format for this is essentially identical to a URI, forming a relative link within the application, though there are differences in the formats. The identifier uses a UUID associated with the record appended to the record location from the API root.

/api/3/alerts/{uuid}

IRIs will be seen in the API typically at the top of a record using the key "@id".

Tooltip

The IRI is automatically generated when inserting the record and is not intended to be used during any POST activities. POST activities should use the "uuid": identifier with a plain 36-character UUID.

Organization

The REST API is organized around the core Modules defined within the platform. Note that most Modules are defined on a 1:1 basis with a database table, though this is not always the case. The root API may be found at https://FortiSOAR_ROOT.URL/api/3, but can only be accessed with the proper authentication. See the Authentication API section in the API Methods chapter for more information.

All Modules and models are made available in the core API, Modules representing a specific data table accessible within the UI. New Modules may be added via the Module Editor in the Administration menu, and every new Module will add a new API endpoint for accessing the records within that Module.

Authentication

Authentication methods for using the API are available via two methods:

  1. Hash-based message authentication code (HMAC) - this method involves computing a specific cryptographic hash via a cryptographic key within the parameters specified from FortiSOAR. This is the required method for permanent API access. See the HMAC Authentication section for more details.
    Note: For HMAC authentication the timestamp must be in UTC format.
  2. Token-based authentication - this method is a temporary access mechanism by using a SHA-256 token, available within the browser resources of the UI. This token expires on a periodic basis and must be refreshed, however, it is useful for temporary access when doing specific API actions during development where generating an HMAC key is not possible, e.g., REST clients and CURL methods.
    The token must be placed in the Header with the Authorization key and the format for identifying the user a Bearer %token%

FortiSOAR utilizes a sessionless security model, meaning the server does not track individual user sessions as objects. Users must be authenticated with a unique token that has a limited lifespan, typically configured at 30 minutes though that may be adjusted. For more information, see the Authentication API section in the API Methods chapter.

Using the HMAC method does not require a session because each message is individually signed with the cryptographic key, but this must be computed, and the server clocks must be in sync for proper operation.

Note

Basic authentication and No authentication webhooks are allowed in the context of the Custom API Endpoint for Playbooks. This is purposeful to reduce the overall risk profile of allowing for less secure methods on the core API.

Authorization

Every API action is reviewed against user authorization privileges. These are determined by your Team membership and Role assignment as described in the "Administration Guide.

Tooltip

We recommend that you always use a limited privilege set scoped to the desired operations to ensure both security and guard against potential data loss due to accidental actions.

Operation

Exercising the API is possible via any valid REST client, such as Postman, or using CURL combined with a user token. All valid CRUD operations allowed via your user privileges may be invoked, but not all endpoints support all HTTP methods.

Supported HTTP Methods

  • GET [Read]
  • POST [Create]
  • PUT [Update]
  • DELETE [Delete]

URI Encoding

The most common format for traversing the API involves using the Module names in the following format.

/api/3/{module name}

An example endpoint for Alerts is as follows:

/api/3/alerts

The body response will include a list of the Alert records found within the database.

{
    "@context": "/api/3/contexts/Alert",
    "@id": "/api/3/alerts",
    "@type": "hydra:PagedCollection",
    "hydra:nextPage": "/api/3/alerts?%24page=2",
    "hydra:totalItems": 1,
    "hydra:itemsPerPage": 30,
    "hydra:firstPage": "/api/3/alerts",
    "hydra:lastPage": "/api/3/alerts?%24page=2",
    "hydra:member": [
        {
        "@id": "/api/3/alerts/028b37fa-bb35-4e3b-8afb-a3274a8cb343",
        "@type": "Alert",
        "name": "Malicious Attachment - Malware.Binary.Vbs",
        "sourceId": null,
        "source": "FireEye EX - Email MPS",
        "origin": "",
        "dueDate": null,
        "description": null,
        "type": null,
        "severity": null,
        "status": null,
        "assignedTo": null,
        "createUser": {
        "@id": "/api/3/appliances/432ba9fe-0955-4379-9177-68b0d87e8caf",
        "@type": "Appliance",
        "name": "Workflow",
        "userId": "7c23b46e-5b84-47c0-8f7f-fe0498156c81",
        "createUser": null,
        "createDate": null,
        "modifyUser": "/api/3/people/bcb46d5a-0ad8-4480-ac68-9ebc28502a30",
        "modifyDate": 1457479171,
        "id": 502,
        "@settings": "/api/3/user_settings/432ba9fe-0955-4379-9177-68b0d87e8caf"
        }]
    "hydra:search": {
    "@type": "hydra:IriTemplate",
    "hydra:template": "/api/3/alerts{?}",
    "hydra:variableRepresentation": "BasicRepresentation",
    "hydra:mapping": []
    }
}

Syntax

FortiSOAR uses the CamelCase format for all data labels, e.g., keys for the key-value pairs in the JSON structure. CamelCase is the practice of writing a compound word or phrase structures where the first letter of the first word is lowercase and subsequent first letters of words following are capitalized.

Tooltip

We recommend you also use CamelCase format during your development to ensure consistency and readability.

Examples

"hydra:variableRepresentation"
"sourceId"
"dueDate"