Malwarebytes Authentication API
The Authentication API from Malwarebytes — 2 operation(s) for authentication.
OpenAPI Specification
openapi: 3.2.0
info:
title: Malwarebytes Authentication API
version: 1.0.0
description: 'Operations tagged Authentication across 2 of this provider''s published API definitions: malwarebytes-threatdown-nebula-openapi.json, malwarebytes-threatdown-oneview-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.threatdown.com
tags:
- name: Authentication
paths:
/oauth2/token:
servers:
- url: https://api.threatdown.com
post:
description: "Use this endpoint to retrieve an authentication token that allows you to send authenticated requests to all the API endpoints.\nFirst, you need to get a valid `client_id`, `client_secret` pair to retrieve an authentication token. See notes below for obtaining a credential pair**.\n\nOnce you have obtained the `access_token`, by adhering to the following specification, you must include it for all the requests to the public APIs along with the `Authorization` header:\n\n```\nAuthorization: Bearer <access_token>\n```\n\n## Request\n\n### Headers\n\nAdd the following headers to your request.\n\n| Name | Description | Type | Required | Default |\n|------|-------------|-------|-----------|----------|\n| Authorization | base64 encoded credential pair* as basic authorization `Basic base64(<client_id>:<client_secret>)`| string | yes | '' |\n| Content-Type | Set to 'application/x-www-form-urlencoded' | string | yes | '' |\n\n*You need to concatenate `client_id` and `client_secret` and encode in base64.\n\nRefer to the following Javascript example to get the correct header's value:\n\n**In the browser**:\n```\n`Basic ${window.btoa(`${clientId}:${clientSecret}`)}`\n```\n\n**NodeJS**:\n```\n`Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`\n```\n\n### Body\nSend the following body with the request.\n\n| Name | Description | Type | Required | Default |\n|------|-------------|-------|-----------|----------|\n| scope | The scope of the token. Can be ```read write execute``` or any subset of those space-separated scopes | string | yes | '' |\n| grant\\_type | The grant\\_type. Set it to `client_credentials` | string | yes | '' |\n\n\n**\\*\\*Note**: To obtain a client ID/client secret pair, open the Nebula\nconsole, go to Settings -> APIs & Integrations. On that\npage, click the \"Add\" button and submit the form. Use the resulting client\nID/client secret pair in your base64 string.\n\n## Response\n\nIf your request successfully processed, our server will respond with a 200 status code and send a JSON body, which will include:\n\n| Name | Description | Type | Can be blank |\n|------|-------------|-------|-----------|\n| access_token | The access token. You need this token to access all other API endpoints | string | no |\n| expires_in | Expiry time in seconds of the access\\_token | number | no |\n| scope | The scope. Can be `read write execute` or a subset of those. Space separate the scope you want to request | string | no |\n| token_type | The type of the token | string | no |\n\nYou can use the `access_token` to send requests to all the other HTTP endpoints.\n\n# Notes\n\nYou can send a raw HTTP request to retrieve the `access_token` following the specification above, but we strongly recommend to using one of the existing `oauth2` libraries.\nLibraries will usually handle refreshing the `access_token`, and generally implements best practices for that authentication protocol. We provide 2 examples as reference:\n\n## Python example\n\nThe following Python examples use the `oauthlib`:\n```python\nfrom requests_oauthlib import OAuth2Session\nfrom oauthlib.oauth2 import BackendApplicationClient\n\nCLIENT_ID = \"\"\nCLIENT_SECRET = \"\"\nCLIENT_ACCOUNT = \"\"\n\ndef NEBULA_URL(path):\n return \"{NEBULA_URL}{PATH}\".format(NEBULA_URL=\"https://api.threatdown.com\", PATH=path)\n\ndef get_nebula_client(client_id, client_secret, account_id):\n client_scope = [\"read\", \"write\"]\n headers = {\"accountid\": account_id}\n\n client = BackendApplicationClient(client_id, scope=client_scope)\n nebula = OAuth2Session(client=client, scope=client_scope)\n nebula.headers.update(headers)\n token = nebula.fetch_token(\n token_url=NEBULA_URL('/oauth2/token'),\n client_secret=client_secret, scope=\" \".join(client_scope))\n return nebula\n\nresp = get_nebula_client(CLIENT_ID, CLIENT_SECRET, CLIENT_ACCOUNT).get(NEBULA_URL('/nebula/v1/account'))\n\nprint(resp.json())\n```\n\n## Javascript example\nThe following Javascript example uses the `simple-oauth2` module available on `npm`:\n\n```javascript\nconst oauth2Module = require('simple-oauth2')\n\nconst CLIENT_ACCOUNT = '<client-account>'\nconst CLIENT_ID = '<client-id>'\nconst CLIENT_SECRET = '<client-secret>'\nconst CLIENT_SCOPE = ['read'];\n\nconst URL = 'https://api.threatdown.com'\nconst TOKEN_PATH = '/oauth2/token'\nconst credentials = {\n client: {\n id: CLIENT_ID,\n secret: CLIENT_SECRET\n },\n auth: {\n tokenHost: URL,\n tokenPath: TOKEN_PATH\n }\n};\n\nconst tokenConfig = {\n scope: CLIENT_SCOPE,\n};\n\nconst oauth2 = oauth2Module.create(credentials);\n\nasync function reqToken() {\n try {\n const result = await oauth2.clientCredentials.getToken(tokenConfig);\n return oauth2.accessToken.create(result);\n } catch (error) {\n throw error;\n }\n}\n\nreqToken()\n .then(({\n access_token,\n expires_in,\n scope,\n token_type\n }) => console.log(\n access_token,\n expires_in,\n scope,\n token_type))\n .catch(e => console.log(e))\n ```\n"
summary: Get an access token
status:
outage:
- oauth2
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: PostDetectionsSearchRes200
properties:
access_token:
type: string
title: Access token to be used to authenticate in API requests
expires_in:
type: number
title: Time in seconds before the token expires
scope:
type: string
title: The granted scope for this access token
token_type:
type: string
title: The type of the token
refresh_token:
type: string
title: With grant type authorization code refresh token gets also returned.
id_token:
type: string
title: With grant type authorization code id token gets also returned.
tags:
- Authentication
operationId: api.oauth2.token
/oneview/oauth2/token:
servers:
- url: https://api.threatdown.com
post:
description: "First, you need to get a valid `client_id`, `client_secret` pair to retrieve an authentication token. See notes below for obtaining a credential pair*.\n\nOnce you have obtained the `access_token`, by adhering to the following specification, you must include it for all the requests to the public APIs along with the `Authorization` header:\n\n```\nAuthorization: Bearer <access_token>\n```\n\n## Request\n\n### Headers\n\nAdd the following headers to your request.\n\n| Name | Description | Type | Required | Default |\n|------|-------------|-------|-----------|----------|\n| Authorization | base64 encoded credential pair* as basic authorization `Basic base64(<client_id>:<client_secret>)`| string | yes | '' |\n| Content-Type | Set to 'application/x-www-form-urlencoded' | string | yes | '' |\n\n*You need to concatenate `client_id` and `client_secret` and encode in base64.\n\nRefer to the following Javascript example to get the correct header's value:\n\n**In the browser**:\n\n```\n`Basic ${window.btoa(`${clientId}:${clientSecret}`)}`\n```\n\n**NodeJS**:\n\n```\n`Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`\n```\n\n### Body\n\nSend the following body with the request.\n\n| Name | Description | Type | Required | Default |\n|------|-------------|-------|-----------|----------|\n| scope | The scope of the token. Can be ```read write execute create:accounts``` or any subset of those space-separated scopes | string | yes | '' |\n| grant\\_type | The grant\\_type. Set it to `client_credentials` | string | yes | '' |\n\n## Response\n\nIf your request successfully processed, our server will respond with a 200 status code and send a JSON body, which will include:\n\n| Name | Description | Type | Can be blank |\n|------|-------------|-------|-----------|\n| access_token | The access token. You need this token to access all other API endpoints | string | no |\n| expires_in | Expiry time in seconds of the access\\_token | number | no |\n| scope | The scope. Can be `read write execute create:accounts` or a subset of those. Space separate the scope you want to request | string | no |\n| token_type | The type of the token | string | no |\n\nYou can use the `access_token` to send requests to all the other HTTP endpoints.\n\n# Notes\nYou can send a raw HTTP request to retrieve the `access_token` following the specification above, but we strongly recommend to using one of the existing `oauth2` libraries.\nLibraries will usually handle refreshing the `access_token`, and generally implements best practices for that authentication protocol. We provide 2 examples as reference:\n\n## Python example\nThe following Python examples use the `oauthlib`:\n```python\nfrom requests_oauthlib import OAuth2Session\nfrom oauthlib.oauth2 import BackendApplicationClient\n\nCLIENT_ID = \"\"\nCLIENT_SECRET = \"\"\nCLIENT_ACCOUNT = \"\"\n\ndef NEBULA_URL(path):\n return \"{NEBULA_URL}{PATH}\".format(NEBULA_URL=\"https://api.threatdown.com\", PATH=path)\n\ndef get_nebula_client(client_id, client_secret, account_id):\n client_scope = [\"read\", \"write\"]\n headers = {}\n\n client = BackendApplicationClient(client_id, scope=client_scope)\n nebula = OAuth2Session(client=client, scope=client_scope)\n nebula.headers.update(headers)\n token = nebula.fetch_token(\n token_url=NEBULA_URL('/oneview/oauth2/token'),\n client_secret=client_secret, scope=\" \".join(client_scope))\n return nebula\n\nresp = get_nebula_client(CLIENT_ID, CLIENT_SECRET, CLIENT_ACCOUNT).get(NEBULA_URL('/oneview/v1/endpoints'))\n\nprint(resp.json())\n```\n\n## Javascript example\nThe following Javascript example uses the `simple-oauth2` module available on `npm`:\n\n```javascript\nconst oauth2Module = require('simple-oauth2')\n\nconst CLIENT_ACCOUNT = '<client-account>'\nconst CLIENT_ID = '<client-id>'\nconst CLIENT_SECRET = '<client-secret>'\nconst CLIENT_SCOPE = ['read'];\nconst URL = 'https://api.threatdown.com'\nconst TOKEN_PATH = 'oneview/oauth2/token'\nconst credentials = {\n client: {\n id: CLIENT_ID,\n secret: CLIENT_SECRET\n },\n auth: {\n tokenHost: URL,\n tokenPath: TOKEN_PATH\n }\n};\n\nconst tokenConfig = {\n scope: CLIENT_SCOPE,\n};\n\nconst oauth2 = oauth2Module.create(credentials);\n\nasync function reqToken() {\n try {\n const result = await oauth2.clientCredentials.getToken(tokenConfig);\n return oauth2.accessToken.create(result);\n } catch (error) {\n throw error;\n }\n}\n\nreqToken()\n .then(({\n access_token,\n expires_in,\n scope,\n token_type\n }) => console.log(\n access_token,\n expires_in,\n scope,\n token_type))\n .catch(e => console.log(e))\n ```\n"
summary: Get an access token
status:
outage:
- oauth2
responses:
'200':
description: response schema
content:
application/json:
schema:
type: object
title: PostDetectionsSearchRes200
properties:
access_token:
type: string
title: Access token to be used to authenticate in API requests
expires_in:
type: number
title: Time in seconds before the token expires
scope:
type: string
title: The granted scope for this access token
token_type:
type: string
title: The type of the token
tags:
- Authentication
operationId: api.oneview.oauth2.token
components:
securitySchemes:
client_credentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: /token
scopes:
read: Read data of your Nebula account
write: Write data, such as groups, policies, exclusions. Create Webhook subscriptions
execute: Issue jobs on your endpoints, like Scan, Reboot or Isolate.
user_permissions:
type: http
scheme: bearer
x-refined-from:
- malwarebytes-threatdown-nebula-openapi.json
- malwarebytes-threatdown-oneview-openapi.json