Public API Specification

Welcome to the Flightdeck API by dope.security. Modify custom categories, get endpoint statuses, and more via API! Stay tuned for upcoming updates that will enhance the capabilities and features of this API.

For details on how to create API client credentials please see API Client Credentials.

Generate Flightdeck API access token

Use this API to generate an access token for use with the Flightdeck API. A valid access token returned from this API is required in all other Flightdeck API calls.

Token generation is based on the OAuth 2.0 Client Credentials Flow. The returned token is used within the HTTP Authorization header as follows:

Authorization: Bearer <access token>

Note:

• The required client_id and client_secret are created by an admin via the dope console.
• Returned access tokens are valid for a limited time period. Clients must check the expires_in value in the response to generate a new access token before the current one expires.
• The OAuth scopes parameter is not supported and if provided will be ignored. The scopes returned in the access token are set directly by the authorization server.

post

/partner/oauth/token

Body

client_idstringrequired

Your application's Client ID.

client_secretstringrequired

Your application's Client Secret.

grant_typestring · enumrequired

The type of grant requested. You must set this to client_credentials

Options: client_credentials

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.flightdeck.dope.security/v1/partner/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{"client_id":"text","client_secret":"text","grant_type":"client_credentials"}'

200

400

401

500

200

{
  "access_token": "eyJz93a...k4laUWw",
  "expires_in": 3600,
  "token_type": "bearer"
}

OK

Generate Flightdeck API access tokens - Example

curl -X 'POST' \
  'https://api.flightdeck.dope.security/v1/partner/oauth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "client_credentials",
  "client_id": "string",
  "client_secret": "string"
}'

List and Search Endpoints

Use this API to get a list of all endpoints, or search for those matching a query parameter.

Note:

• To return a list of all endpoints do not include any additional parameter.
• Only one of the optional parameters is allowed to be specified per request.
• Results are returned in pages using cursor based pagination and ordered by the lastSeen property.

get

/endpoints/search

Authorizations

Query parameters

idstring

Broad search query across endpoints by device, user and email identities that contain this string (case-insensitive)

emailIdstring

Search by email ids that contain this string (case-insensitive)

deviceNamestring

Search by device names that contain this string (case-insensitive)

userIdstring

Search by user ids that contain this string (case-insensitive). userId for OIDC users is usually their email address.

osVersionstring

Filter by this exact device OS version string

statusstring · enum[]

Filter by this exact set of status'

debugStatestring · enum[]

Filter by this exact set of debug states. 0 means not in debug 1 means debug request sent to endpoint 2 means debug request acknowledged by endpoint

fallbackModestring · enum

Filter by the fallback mode

Options: true, false

locationIdstring

Filter by this exact location id - with an underscore separating the case sensitive city and country values e.g. "City_Country"

agentVersionstring

Filter by this exact agent version

firstnumber

An optional pagination param that states the number of records requested from the start of the cursor.

afterstring

An optional pagination param that contains the current cursor and indicates that records after the current cursor are requested.

orderstring · enum

The direction of the sort by the lastSeen property. The default is to sort by descending

Options: desc, asc

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.flightdeck.dope.security/v1/endpoints/search' \
  --header 'Authorization: Bearer JWT'

200

400

403

500

200

{
  "data": {
    "pageInfo": {
      "endCursor": "text",
      "hasNextPage": true
    },
    "endpoints": [
      {
        "agentUUID": "10e68510c-0885-4943-a8b0-b6feb29a9f81",
        "userUUID": "24c38805-1289-44fa-b974-2071a1702ba9",
        "agentVersion": "1.0.00000",
        "binaryType": "x86",
        "cityName": "Cork",
        "region": "Munster",
        "countryName": "Ireland",
        "cpuFamily": "Apple M1 Max",
        "debugState": "1",
        "deviceName": "Dope-MacBook-Pro.local",
        "disableMode": false,
        "errorMessage": "Agent is not running.",
        "fallbackMode": false,
        "configurationLastUpdated": "2023-10-10T10:10:00-0000",
        "osVersion": "Mac13",
        "policyName": "Base Policy",
        "realtimeConnection": true,
        "status": "healthy",
        "lastSeen": "2023-10-10T10:10:00-0000",
        "userId": "dope-user",
        "emailId": "[e-mail]"
      }
    ]
  }
}

OK

List and Search Endpoints - Examples

List all endpoints

curl -X 'GET' \
  'https://api.flightdeck.dope.security/v1/endpoints/search' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer access_token'

Search by email address

curl -X 'GET' \
  'https://api.flightdeck.dope.security/v1/endpoints/search?emailId=string' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer access_token'

Add URLs to a Custom Category

Use this API to add URLs to an existing custom category.

Specify the name of the custom category in the path parameter (custom_category_name) and provide a JSON array of URLs in the request body.

Ensure that URLs are properly formatted and included in the array.

post

/custom_categories/{custom_category_name}/urls

Authorizations

Path parameters

custom_category_namestringrequired

The name of the custom category to add URLs to

Body

dataobject

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.flightdeck.dope.security/v1/custom_categories/{custom_category_name}/urls' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"data":{"urls":["dope.security","google.com"]}}'

200

400

403

500

200

No body

OK

Add URLs to a Custom Category - Example

curl -X 'POST' \
  'https://api.flightdeck.dope.security/v1/custom_categories/string/urls' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access_token'
  -d '{
  "data": {
    "urls": [
      "dope.security",
      "google.com"
    ]
  }
}'

Delete a specific URL from a Custom Category

Use this API to delete a specific URL from an existing custom category.

Specify the name of the custom category in the path parameter (custom_category_name).

Ensure that a given URL is encoded using URL encoding.

delete

/custom_categories/{custom_category_name}/url/{encoded_url}

Authorizations

Path parameters

custom_category_namestringrequired

The name of the custom category to delete given URL from

encoded_urlstringrequired

The URL to be deleted (Ensure that URLs are properly URL-encoded using the UTF8 encoding method)

Example: https%3A%2F%2Fdope.security

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.flightdeck.dope.security/v1/custom_categories/{custom_category_name}/url/{encoded_url}' \
  --header 'Authorization: Bearer JWT'

200

400

403

500

200

No body

OK

Delete a specific URL from a Custom Category - Example

curl -X 'DELETE' \
  'https://api.flightdeck.dope.security/v1/custom_categories/some_category_name/url/url_encoded_string' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer access_token'

Delete All URLs from a Custom Category

Use this API to delete all URLs from an existing custom category.

Specify the name of the custom category in the path parameter (custom_category_name).

This action will remove all URLs associated with the specified custom category.

delete

/custom_categories/{custom_category_name}/urls

Authorizations

Path parameters

custom_category_namestringrequired

The name of the custom category to delete all URLs from

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.flightdeck.dope.security/v1/custom_categories/{custom_category_name}/urls' \
  --header 'Authorization: Bearer JWT'

200

400

403

500

200

No body

OK

Delete All URLs from a Custom Category

curl -X 'DELETE' \
  'https://api.flightdeck.dope.security/v1/custom_categories/string/urls' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer access_token'

List all URLs of a Custom Category

Use this API to get all URLs of an existing custom category.

get

/custom_categories/{custom_category_name}/urls

Authorizations

Path parameters

custom_category_namestringrequired

The name of the custom category to get URLs from

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.flightdeck.dope.security/v1/custom_categories/{custom_category_name}/urls' \
  --header 'Authorization: Bearer JWT'

200

400

403

500

200

{
  "data": {
    "urls": [
      "dope.security",
      "google.com"
    ]
  }
}

OK

---

curl -X 'GET' \
  'https://api.flightdeck.dope.security/v1/custom_categories/some_category_name/urls' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer access_token'

We have provided our partner .yaml file below, available for download. This can be used with API tools like Swagger, Postman, etc.

20KB

partner_api_1.0.2.yaml

Partner YAML file