Skip to main content

Using the Blumira Public API in Beta

  • Updated

Overview

Blumira offers a limited beta version of a public API that is OpenAPI Specification v3 compliant and is only offered to accounts on our XDR edition (and MSP accounts). Below, you can find out how to gain access to explore the available endpoints.

Note: If you are interested in joining the private beta, click the blue "Feedback" button below and submit a request to our team. Your account must be on a paid edition to join the beta.

About the Endpoints

The endpoints available in the core API are all scoped for READ-ONLY (RO) access and will be rate-limited at 10 requests per second per key. The following endpoints are available:

  • /findings - Get findings for an org

  • /findings/{id} - Get a specific finding

  • /findings/{id}/comments - Get comments for a specific finding

  • /findings/{id}/details/ - Get details of a finding

The best way to explore the API endpoints, available arguments, and sample returns is by importing the blumira-api-oas.json file into a tool like Postman or Swagger Editor. You can then explore and use the API to build workflows or alerts in the tools that are most important to your team. Example responses from the API are included at the end of this article.

Using the API

Obtaining a key pair

To use the Blumira Public API, you need a key pair for your account. If you have multiple accounts or manage sub-accounts as an MSP, you will still need one key pair for each account because parent-child account relationships are not yet supported.

Note: We will not provide more than one key pair per organization.

To obtain a key pair:

  1. If you are an MSP or you are on the XDR edition, click Feedback in the lower-right corner, and then request to participate in the Beta.
  2. A Product Manager will review your request and, if approved, will send the following key pair information to you:
    • client_id
    • client_secret

Generating a JWT bearer token

Access to the API requires authorization with a JWT bearer token. Below is an example of a cURL command used to create the token. When running your own command in your preferred language, ensure you replace the client_id and client_secret with the values given to you in the key pair for your account.

  curl --request POST \
  --url https://auth.blumira.com/oauth/token \
  --header 'content-type: application/json' \
  --data "{\"client_id\":\"$CID\",\"client_secret\":\"$SEC\",\"audience\":\"public-api\",\"grant_type\":\"client_credentials\"}"

Example token output:

{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlFrRTVNREUxUVRKR05UbEJOVGREUlRKRE1rUkdOMEZFTXpreFJEa3pOelJFUmpKQlFVUTROUSJ9.eyJwb2wiOiJ4ZHJfcnciLCJvcmciOiJmZmZmZmZmZi1mZWVkLWJlZWYtMTMzNy1jMGZmZWUwMDAwMDIiLCJpc3MiOiJodHRwczovL2F1dGguZC5iNWEuaW8vIiwic3aaaaaaaaFIY0lIYmhqNFVJVVdTQzE1OGp3NVloYmRWZTluOUNAY2xpZW50cyIsImF1ZCI6InB1YmxpYy1hcGkiLCJpYXQiOjE3MzQwMjg1ODIsImV4cCI6MTczNjYyMDU4Miwic2NvcGUiOiJydyIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyIsImF6cCI6InhBSGNJSGJoajRVSVVXU0MxNThqdzVZaGJkVmU5bjlDIn0.JF87Yx9sBBiIOJ0rM6IAO6Rv4xs9LD_L_nwF5zMLdQlYYHnKCYuRbWYQiih5ITi_SkL2HG6Aa89XDKZ32jD2N5U7V6RE7AxGJteQBNU5AtijmimBORTdZz9gr3g5ol_R4H1TRpapVeIYwebjVy9TE1h-V7xaP9CTnBUKSv2KIqaT6Gysz79isOd0Pjj_SzF89inSb44oND_Yam5qayYaql1rTKSKJQvLf-hvedKXM088fGG6xTQivoamgVIKZIEpVeBSTMzC22rrITwAcanWxLjVfI5yoChoqca1U8SKKg5AsJ9b5GLh28r6wH3BIHgd5sIVCT0NewC_kA4xxxxxx","scope":"ro","expires_in":2592000,"token_type":"Bearer"}

In your preferred API platform, use the token to authorize into the Blumira Public API. This is a bearer token, which can be used as follows:

curl --url https://api.blumira.com/public-api/v1/findings -H "Authorization: Bearer ${JWT}"

Important: The token is valid for about 30 days and then must be refreshed. 

Example API responses by endpoint

Findings

Command:

curl --url "https://api.blumira.com/public-api/v1/findings?page_size=2" -H "Authorization: Bearer <JWT_TOKEN>"

Response:

{
  "data": [
    {
      "analysis": "<p> Blumira has detected an unusual signin to your Azure Active Directory by Lorem Ipsum from 2601:547:ce01:cbf0:61dd:548e:f197:6cbf. </p>\n\n<p> Blumira believes that this activity is unusual due to the reported client application completing the authentication:</p>\n<p>\n <ul>\n  <li>azsdk-net-Identity/1.13.2 (.NET 8.0.13; CBL-Mariner/Linux)</li>\n  <li></li>\n  <li>Security Copilot</li>\n</ul> \n</p>",
      "created": "2025-02-25T16:36:15.669882Z",
      "id": "9b094ab5-143c-4532-b938-b975e40a6357",
      "name": "Indicator: T1078.004 AzureAD Anomalous Agent Signin Activity",
      "org_id": "9afe8a19-f1b2-4348-8634-7e3e85e67f14",
      "priority": 2,
      "short_id": "F-25-08-9B09",
      "status_name": "Open",
      "type_name": "Suspect"
    },
    {
      "analysis": "<p>User user@blumira.com has granted the application \"user_ingestion\" consent to access their data in your organization's Microsoft 365 tenant. Only approved applications with a legitimate business use case should have permissions to access sensitive data like contact information, email, or documents. Unexpected 'Consent to Application' activity to an unapproved application may indicate successful consent phishing by a threat actor. </p> <p>Microsoft 365 links to additional :<ul> <li><a href=\"https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Overview/appId/8dcdf018-75a1-44e6-8ee6-c2e15eb9d539\" target=\"_blank\" rel=\"noopener noreferrer\">user_ingestion Overview</a></li> <li><a href=\"https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/CallAnAPI/appId/8dcdf018-75a1-44e6-8ee6-c2e15eb9d539\" target=\"_blank\" rel=\"noopener noreferrer\">user_ingestion Permissions</a></li> </ul></p> <p>For more information about Microsoft 365 Consent Phishing, see the Microsoft documentation: <a href=\"https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/protect-against-consent-phishing?source=recommendations\" target=\"_blank\" rel=\"noopener noreferrer\">Protect against consent phishing</a>.</p>",
      "created": "2025-02-24T17:58:30.405283Z",
      "id": "5aad37f8-73af-40ab-81b3-ae927cc9a662",
      "name": "Microsoft 365: Consent to Application Granted",
      "org_id": "9afe8a19-f1b2-4348-8634-7e3e85e67f14",
      "priority": 1,
      "short_id": "F-25-08-5AAD",
      "status_name": "Open",
      "type_name": "Operational"
    }
  ],
  "links": {
    "next": "/v1/findings?page=2&page_size=2&limit=200&order_by=created%3Bdesc",
    "prev": null,
    "self": "/v1/findings?page_size=2&limit=200&order_by=created%3Bdesc"
  },
  "meta": {
    "page": 1,
    "page_size": 2,
    "total_items": 200,
    "total_pages": 100
  },
  "status": "OK"
}

Findings/<ID>

Command:

curl --url "https://api.blumira.com/public-api/v1/findings/5aad37f8-73af-40ab-81b3-ae927cc9a662" -H "Authorization: Bearer <JWT_TOKEN>"

Response:

{
  "analysis": "<p>User user@blumira.com has granted the application \"user_ingestion\" consent to access their data in your organization's Microsoft 365 tenant. Only approved applications with a legitimate business use case should have permissions to access sensitive data like contact information, email, or documents. Unexpected 'Consent to Application' activity to an unapproved application may indicate successful consent phishing by a threat actor. </p> <p>Microsoft 365 links to additional :<ul> <li><a href=\"https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Overview/appId/8dcdf018-75a1-44e6-8ee6-c2e15eb9d539\" target=\"_blank\" rel=\"noopener noreferrer\">user_ingestion Overview</a></li> <li><a href=\"https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/CallAnAPI/appId/8dcdf018-75a1-44e6-8ee6-c2e15eb9d539\" target=\"_blank\" rel=\"noopener noreferrer\">user_ingestion Permissions</a></li> </ul></p> <p>For more information about Microsoft 365 Consent Phishing, see the Microsoft documentation: <a href=\"https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/protect-against-consent-phishing?source=recommendations\" target=\"_blank\" rel=\"noopener noreferrer\">Protect against consent phishing</a>.</p>",
  "created": "2025-02-24T17:58:30.405283Z",
  "id": "5aad37f8-73af-40ab-81b3-ae927cc9a662",
  "name": "Microsoft 365: Consent to Application Granted",
  "org_id": "9afe8a19-f1b2-4348-8634-7e3e85e67f14",
  "priority": 1,
  "short_id": "F-25-08-5AAD",
  "status_name": "Open",
  "type_name": "Operational"
}

Findings/<ID>/detail

Command:

curl --url "https://api.blumira.com/public-api/v1/findings/5aad37f8-73af-40ab-81b3-ae927cc9a662/details" -H "Authorization: Bearer <JWT_TOKEN>"

Response:

{
  "analysis": "<p>User user@blumira.com has granted the application \"user_ingestion\" consent to access their data in your organization's Microsoft 365 tenant. Only approved applications with a legitimate business use case should have permissions to access sensitive data like contact information, email, or documents. Unexpected 'Consent to Application' activity to an unapproved application may indicate successful consent phishing by a threat actor. </p> <p>Microsoft 365 links to additional :<ul> <li><a href=\"https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Overview/appId/8dcdf018-75a1-44e6-8ee6-c2e15eb9d539\" target=\"_blank\" rel=\"noopener noreferrer\">user_ingestion Overview</a></li> <li><a href=\"https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/CallAnAPI/appId/8dcdf018-75a1-44e6-8ee6-c2e15eb9d539\" target=\"_blank\" rel=\"noopener noreferrer\">user_ingestion Permissions</a></li> </ul></p> <p>For more information about Microsoft 365 Consent Phishing, see the Microsoft documentation: <a href=\"https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/protect-against-consent-phishing?source=recommendations\" target=\"_blank\" rel=\"noopener noreferrer\">Protect against consent phishing</a>.</p>",
  "category_name": "Initial Access",
  "created": "2025-02-24T17:58:30.405283Z",
  "id": "5aad37f8-73af-40ab-81b3-ae927cc9a662",
  "jurisdiction_name": "responder",
  "name": "Microsoft 365: Consent to Application Granted",
  "org_id": "9afe8a19-f1b2-4348-8634-7e3e85e67f14",
  "owners": {
    "analysts": [],
    "managers": [],
    "responders": []
  },
  "priority": 1,
  "resolution_name": null,
  "short_id": "F-25-08-5AAD",
  "status_name": "Open",
  "summary": "Microsoft 365: Consent to Application Granted",
  "type_name": "Operational",
  "url": "https://app.blumira.com/9afe8a19-f1b2-4348-8634-7e3e85e67f14/query/findings/5aad37f8-73af-40ab-81b3-ae927cc9a662"
}

Findings/<ID>/comments

Command:

curl --url "https://api.blumira.com/public-api/v1/findings/5aad37f8-73af-40ab-81b3-ae927cc9a662/comments" -H "Authorization: Bearer <JWT_TOKEN>"

Response:

[
  {
    "age": 3,
    "body": "<div>JP making sample comment for API</div>",
    "subject": null
  }
]

Health

Command:

curl --url "https://api.blumira.com/public-api/v1/health" -H "Authorization: Bearer <JWT_TOKEN>"

Response:

{
  "data": {
    "api_name": "Blumira Public API",
    "build_time": "2025-02-28T16:11:11Z",
    "commit_hash": "68b60e5c"

 

 

 

Was this article helpful?
0 out of 0 found this helpful
Return to top