LogoLogo
  • Introducing dope.swg
    • Changing the Rules...
    • Quick Start Guide
      • Create a dope.swg Account
      • Get Started with the dope.endpoint
      • Import User and Group Data
      • Create a dope.swg Web Policy
    • Mitre ATT&CK and Nist CSF
  • dope.console
    • Analytics
      • Overview dashboard
      • Policy View
      • Productivity
      • Shadow IT
      • Detail View
    • dope.swg Policy
      • Editing the Base Policy
      • Adding Policy Exceptions
      • Assigning a Block Page
      • Creating Custom Categories
      • URL Bypass List
      • Application Bypass List
      • Default Bypass List
      • Cloud Application Control (CAC)
        • Microsoft O365
        • Google
        • Box
        • Salesforce
        • Dropbox
        • Slack
        • WebEx
      • Custom Policy
      • Policy Assignment
      • Policy Inheritance and Customization
    • CASB Neural
      • Microsoft 365 - Authentication
      • Google - Authentication
      • CASB DLP
        • DLP Files Table
    • Endpoint Manager View
      • Searching the View
      • Filtering and Sorting the Endpoint View
      • Endpoint Count
      • Running Diagnostics
      • Disable Endpoint
    • Settings
      • General
      • Block Pages
      • Endpoints
      • Users
        • Importing from Google
        • Why not SAML & SCIM?
      • Audit Log
      • SIEM Integration
        • Category & Verdict Mappings
      • API Client Credentials
      • Billing Details
    • Notifications
      • SSL Errors
  • dope.endpoint
    • Trusted Process Names
    • Generate Diagnostics
    • Disable Endpoint
    • Installing using MDM on Mac
      • Using JAMF
      • Using Kandji
      • Using Intune
    • Installing using Intune on Win
    • Mac Installer
      • Installation Process - Silent
      • Uninstall
      • Endpoint Authentication
    • Windows Installer
      • Installation Process - Silent
      • Uninstall
      • Endpoint Authentication
    • dope.endpoint UI
      • Windows UI
      • macOS UI
    • Automatic Updates
  • Release Notes
  • DOPE.APIs
    • Public API Specification
Powered by GitBook
On this page
  1. DOPE.APIs

Public API Specification

PreviousRelease Notes

Last updated 8 months ago

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.

20KB
partner_api_1.0.2.yaml
Partner YAML file

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
OK
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"
    ]
  }
}
  • POSTGenerate Flightdeck API access token
  • Generate Flightdeck API access tokens - Example
  • GETList and Search Endpoints
  • List and Search Endpoints - Examples
  • List all endpoints
  • Search by email address
  • POSTAdd URLs to a Custom Category
  • Add URLs to a Custom Category - Example
  • DELETEDelete a specific URL from a Custom Category
  • Delete a specific URL from a Custom Category - Example
  • DELETEDelete All URLs from a Custom Category
  • Delete All URLs from a Custom Category
  • GETList all URLs of a Custom Category

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

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

No content

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

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

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

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
OK
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
}
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"
      }
    ]
  }
}