Skip to main content

Sonrai's GraphQL API Library

One-Click Least Privilege. Zero Disruption.



© 2025 Sonrai Security. All rights reserved.

Overview​

The Sonrai GraphQL API library allow users to programatically run GraphQL queries for data and mutations to make updates & configuration changes, similar to the GraphQL commands in use by the user interface which can be run in the CPF application using Advanced Search or from external tools.

Sonrai's API allows your security workflows, automation tools, and reporting systems to access identity, entitlement, and permission data as well as controls implmented within CPF.

  • GraphQL API: Supports both queries and mutations.
  • Token-based Auth: Uses short-lived API tokens with RBAC enforcement; tokens inherit creator privileges.
  • Advanced Use Cases: Supports “non-person” integration identities, JIT access, least privilege auditing, privilege right-sizing, quarantine actions, and remediation.

Reference: Learn more about the GraphQL query language.


Getting Started: Tools & Setup​

While you can use the Advanced Search page to submit GraphQL API requests directly in the CPF interface, the following external tools are recommended for more complex use cases:

Quick Start Overview​

  1. Generate a Sonrai API token (see Authentication).
  2. Get your Org ID (see your profile menu in the Sonrai UI).
  3. In your preferred tool (Postman, Insomnia, curl), set:
    • Authorization header to Bearer <your-token>
    • sonraisecurity-com-org: <yourOrgId>
    • API URL: <https://<yourOrgID>>.sonraisecurity.com/graphql
  4. Test a simple query:
Create Sonrai API token
query {
  SonraiCurrentUsers {
    items { email }
  }
}
  1. You should receive a JSON response listing your user/email. Now you’re ready!

Best Practices​

  • Short-lived tokens: Use the minimal necessary lifetime for tokens.
  • Audit: All token creation/deletion is logged in Sonrai's User Activity.
  • Integration Identities: Use NPIs or automation-specific users for CI/CD, scripts, and integrations.
  • Scoping: Always scope queries and mutations to the minimal set (specific accounts/OUs/services).
  • Rate limiting: If you see 429 Too Many Requests, pause/retry after a delay.

Troubleshooting & Rate Limiting​

  • 429 Errors: Reduce query frequency, implement exponential backoff/retries.
  • Tokens not working: Confirm you’re using an unexpired token, with the correct permissions for the data/mutation.
  • Schema changes: Use Insomnia/Postman’s “Refresh Schema” feature for up-to-date API docs and autocomplete.
  • Org ID Issues:
    • Use your Org ID (<orgid>.sonraisecurity.com/graphql).
    • Or use the full org name if no ID is present.

Authentication​

Generating an API Token​

  • Create tokens via UI (Advanced Search) or API. Tokens last from 2 hours up to 30 days.
  • Non-Person Identities: For automation or integrations, create a user/service account in Sonrai, login, and generate a token.
Create Sonrai API token
mutation createToken {
  GenerateSonraiUserToken(input: {
    expiresIn: 7200 # seconds (2 hours)
    name: "automation-token"
  }) {
    name
    expireAt
    token  # Only returned at creation!
  }
}

Security Note: Treat tokens as secrets. Store securely; tokens are not retrievable after creation. Expired tokens auto-delete.

Using the Token​

  • Add as a Bearer Token in the Authorization header.
  • API endpoint: <https://<yourOrgID>>.sonraisecurity.com/graphql
  • In tools (Postman, Insomnia):
Headers: sonraisecurity-com-org: <yourOrgId>
Auth: Bearer <your token>

Enabling a "Non Person" Identity for Integrations​

To create a non-person identity (NPI) for use with integrations, there are a couple of different options:

For organizations who leverage SSO, work with your identity management team to complete these steps:

  1. Create a role "address" within your IAM infrastructure
  2. Create a user within the Sonrai platform (for the above user)
  3. Login to the Sonrai platform via SSO
  4. Generate the API token

For organizations that do not use SSO or have a secondary email domain, work with your identity management team to complete these steps:

  1. Configure a mail alias
    (Example: sonrai-api@mycompany.com)
  2. Redirect the alias to a user within your organization
  3. Create a user within the Sonrai platform (for the above user)
  4. Login to the Sonrai platform
  5. Generate the API token

Common Use Cases & Example Queries​

List All AWS Accounts in My Org​

Example query
query getCloudHierarchyList($filters: CloudHierarchyFilter) {
  CloudHierarchyList(where: $filters) {
    items { 
      name 
      cloudType 
      scope 
      parentScope 
      scopeFriendlyName 
   }
  }
}
Variables
{ "filters": { "cloudType": { "op": "EQ", "value": "aws" } } }

All Identities with Excessive Privileges​

Example query
query getExcessivePrivilegeIdentitiesCount($filters: ExcessiveIAMPrivilegeFilter!) {
  ExcessiveIAMPrivilege(where: $filters) { 
    count
    items {
      account
      accountName
      scope
      identityCount
      identities {
        resourceId
        name
        isSSO
        ssoActorId
      } 
    } 
  }
}
Variables
{ "filters": { "scope": { "value": "aws/x-xxxx", "op": "STARTS_WITH" } } }

(Adapt scope as needed, e.g., for a specific AWS OU or account.)

List all Roles created in the last 30 days​

Example query
query getRoles {
  ListResourceSummaries(
    where: {
      type: { op: EQ, value: "Role" },
      active: { op: EQ, value: true }
      createdDate: { op: GT, function: { dateTimeNow: { offsetDays: -30 } } }
    }
  ) {
    items {
      name
      resourceId
      account
      createdDate
      srn
    }
  }
}

Fetch All Third Parties with Access​

Example query
query getThirdParties($scope: String!) {
  ThirdParties(where: {scope: {value: $scope, op: EQ}}) {
    items {
      thirdPartyFriendlyName
      status { state }
      accountCount
      lastAccessed
    }
  }
}
Variables
{ "scope": "aws/x-xxxx" }

Get Sensitive Permissions Used in a Service​

Example query
query getCloudControls($filter: CloudControlFilter) {
  CloudControls(where: $filter) {
    items {
      controlId
      controlType
      controlKey
      cloudType
      serviceType
      serviceFriendlyName
      permissions {
        permissionId
        permission
        description
        mitreTactics {
          mitreTacticId
          description
          name
        }
      }
    }
  }
}
Variables
{
  "filter": {
    "controlKey": {
      "op": "EQ",
      "value": "ec2"
    },
    "controlType": {
      "op": "EQ",
      "value": "Permissions"
    },
    "cloudType": {
      "op": "EQ",
      "value": "aws"
    }
  }
}

Get Unused Identities (Dormant for 90+ Days)​

Example query
query getUnusedIdentities($filters: UnusedIdentitiesFilter!) {
  UnusedIdentities(where: $filters) {
    items { 
      account 
      count
      identities {
        actorName
        actorId
        lastSeen
      }
    }
  }
}
Variables
{
  "filters": {
    "scope": { "value": "aws/x-xxxx", "op": "STARTS_WITH" },
    "daysSinceLastLogin": { "op": "EQ", "value": "90" }
  }
}

Describe a Resource’s AWS Policy (e.g., S3 Bucket)​

Example query
query fetchResourcePolicy($resourceSrn: String!) {
  DescribeAWSDirectPolicy(where: {srn: {op: EQ, value: $resourceSrn}}) {
    items { policyJson }
  }
}
Variables
{ "resourceSrn": "srn:aws:s3::123456789012/DataContainer/my-bucket" }

JIT Access: Get JIT Sessions in a Scope​

Example query
query getJitSessions($scope: String!) {
  JitSessions(where: { scope: { op: STARTS_WITH, value: $scope } }) {
    items {
      id
      identity
      permissionSet {
        name
      }
      expiry
      approvedAt
      approvedBy
      identityFriendlyName
    }
  }
}
Variables
{ "scope": "aws/x-xxxx" }

Mutation Examples (Actions & Updates)​

Create/Rotate an API Token​

mutation createToken {
  GenerateSonraiUserToken(input: {
    expiresIn: 28800
    name: "nightly-automation"
  }) {
    name
    token
    expireAt
  }
}

Delete/Expire a Token​

mutation revokeToken {
  DeleteSonraiUserToken(input: {
    srn: "[token-srn]"
  })
}