Overview

Last modified on August 10, 2022

The strongDM API allows users of strongDM to programmatically interact with their organization in strongDM in order to create, remove, or manage Users, Roles, permissions, Gateways, Relays, resources, and more. The amount of API access afforded to an API key depends entirely on what was granted to the key by the organization’s administrators when the key was created.

The strongDM API is constructed with gRPC and a request signature model that requires the use of one of the strongDM SDKs to interface with the API. The SDKs were designed with REST principles in mind. They are built around a set of domain objects, as well as the basic set of REST verbs: Create, Read, Update, and Delete.

The preferred destination for requests directly to the strongDM API is to the domain api.strongdm.com. However, if you must use static IP addresses, you will need to use one of these:

  • 75.2.121.26
  • 99.83.168.70

It is also recommended that if you have any kind of IP allow list or safe list, you add these IPs there as well.

Domain Objects

Domain objects are present in all of the strongDM SDKs. These domain objects are, in a way, the glossary of the API. Once you’re familiar with them, you’ll better understand what you can do with the API.

Domain ObjectDescription
AccountAttachmentAssigns an Account to a Role
AccountGrantGrants resource access to directly to an Account
AccountA generic term for the type of account: a regular User account, for humans who are authenticated through username/password or SSO; or a Service Account, for machines that are authenticated using a service token
NodeThe Gateway(s) and Relay(s) that make up your strongDM network, proxying connections from your users to your resources. Gateways listen for connections from strongDM clients and securely connect them to resources. Relays are similar to Gateways but are only placed in secured networks. Relays extend the reach of a Gateway to additional resources, while maintaining the egress-only nature of the firewall. They do not listen for incoming connections, but instead only reach out to establish connections.
ResourceCan be a database, server, cluster, website, or cloud that strongDM delegates access to
RoleAttachmentAssigns a Role to a composite role
RoleGrantGrants resource access to a Role and then permits members of the Role to access that resource
RoleA collection of access grants, typically corresponding to a team name or business unit function, such as DevOps

How it Works

The strongDM API does not rely on bearer tokens alone to protect your requests (and thus your infrastructure). Instead, the strongDM API requires the use of request signatures modeled on the AWS V4 signing process. This methodology never sends a secret key over the network. If the key isn’t sent, the key cannot be intercepted. Furthermore, this methodology allows strongDM to validate the time and payload of each API call, protecting against replay attacks or Man in the Middle (MitM) message tampering. The strongDM SDKs handle the gRPC calls and signing process to ensure a consistent and convenient experience.

Authentication

Each SDK provides a client that must be constructed with an API ID and Secret (also referred to as your “API key”). This key will also set the client’s permission to manage objects within strongDM. For instructions on creating your API key, see the API Keys page.

For example, in Python:

def main():
    client = strongdm.Client(<YOUR-ID>,<YOUR-SECRET>)

Requests

Each domain object is accessible via functions or methods provided by the client.

For example, in Ruby:

users = client.accounts.list("")

Filters

Many domain objects provide a common filtering language. You can use filters to narrow results from most Read operations when making requests.

For example, in Go:

users, err := client.Accounts().List(ctx, "firstName:Alice")
if err != nil {
  log.Fatal("failed to query accounts:", err)
}

In the example above, only users matching the first name “Alice” will be returned.

Paginate Results

When making a request with a Read operation that will return many results, the SDK will automatically paginate the results. Depending on the language, pagination may be modeled as a transparent iterator, as in Ruby:

users.each do |user|
    p user
end

or an explicit call to receive the next result, as in Go:

for users.Next() {
    user := users.Value()
    fmt.Println(user)
}

Rate Limits

Requests are subject to rate limits. Default rate limits are generous, and it’s unlikely that you’ll reach rate limits during normal operations. If you do, however, encounter a rate limit for a valid use case, please notify support@strongdm.com to have your rate limit increased.

The following Python snippet illustrates the expected behavior for a rate-limited call. Note the remaining attribute on the returned RateLimitError, which quantifies the remaining call budget for this time period (in this case, 0):

try:
    self.client.roles.get(role.id)
except sdm.errors.RateLimitError as ex:
    self.assertEqual(ex.rate_limit.limit, 1)
    self.assertEqual(ex.rate_limit.remaining, 0)

The strongDM SDKs

strongDM supports the following SDK options:

LanguageReferenceGitHubExamples
RubyRubyDocstrongdm-sdk-rubyRuby SDK Examples
Pythonpdocsstrongdm-sdk-pythonPython SDK Examples
Javajavadocstrongdm-sdk-javaJava SDK Examples
Gopkg.go.devstrongdm-sdk-goGo SDK Examples

Additionally, strongDM’s Terraform provider makes use of the strongDM API and has a set of Terraform provider examples as well.

The strongDM API allows for the programmatic management of strongDM features as well as the resources attached to the organization. You can interact with the API via any of strongDM’s SDKs or Terraform. The SDK offerings may expand over time, as well. Feel free to use the SDKs to interact with strongDM from your own software, and contact support@strongdm.com if you have any questions or concerns.

Top