Public API Specification

Last updated 9 months ago

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 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 - 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 - 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 - 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

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

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.

PreviousRelease Notes

Last updated 9 months ago

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

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 - 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 - 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 - 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

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

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.

List all URLs of a Custom Category

get

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

Authorizations

Path parameters

custom_category_namestringRequired

The name of the custom category to get URLs from

Responses

200

application/json

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error. Retry the request again with an exponential back-off.

application/json

get

GET /v1/custom_categories/{custom_category_name}/urls HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer JWT
Accept: */*

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

List and Search Endpoints

get

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.

Authorizations

Query parameters

idstringOptional

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

emailIdstringOptional

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

deviceNamestringOptional

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

userIdstringOptional

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

osVersionstringOptional

Filter by this exact device OS version string

fallbackModestring · enumOptional

Filter by the fallback mode

Possible values:

locationIdstringOptional

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

agentVersionstringOptional

Filter by this exact agent version

firstnumberOptional

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

afterstringOptional

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

orderstring · enumOptional

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

Possible values:

Responses

200

application/json

400

Bad request

application/json

403

Access denied

application/json

500

Internal server error. Retry the request again with an exponential back-off.

application/json

get

GET /v1/endpoints/search HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer JWT
Accept: */*

{
  "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": "givenName.familyName@dope.security"
      }
    ]
  }
}

Delete a specific URL from a Custom Category

delete

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.

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

200

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error. Retry the request again with an exponential back-off.

application/json

delete

DELETE /v1/custom_categories/{custom_category_name}/url/{encoded_url} HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer JWT
Accept: */*

No content

Delete All URLs from a Custom Category

delete

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.

Authorizations

Path parameters

custom_category_namestringRequired

The name of the custom category to delete all URLs from

Responses

200

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error. Retry the request again with an exponential back-off.

application/json

delete

DELETE /v1/custom_categories/{custom_category_name}/urls HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer JWT
Accept: */*

No content

Generate Flightdeck API access token

post

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.

Body

grant_typestring · enumRequired

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

Possible values:

client_idstringRequired

Your application's Client ID.

client_secretstringRequired

Your application's Client Secret.

Responses

200

application/json

400

Bad request

application/json

401

Client not authorized

application/json

500

Internal server error. Retry the request again with an exponential back-off.

application/json

post

POST /v1/partner/oauth/token HTTP/1.1
Host: api.flightdeck.dope.security
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "grant_type": "client_credentials",
  "client_id": "text",
  "client_secret": "text"
}

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

Add URLs to a Custom Category

post

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.

Authorizations

Path parameters

custom_category_namestringRequired

The name of the custom category to add URLs to

Body

Responses

200

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error. Retry the request again with an exponential back-off.

application/json

post

POST /v1/custom_categories/{custom_category_name}/urls HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 48

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

No content