API Conventions

The following explains conventions that apply to all of Data Theorem’s APIs. There may be some exceptions, but they will be documented.

API Versioning

All of Data Theorem’s publicly facing APIs use semantic versioning for APIs. A particular API incorporates its major version of the API into its URL. For example:

https://api.securetheorem.com/apis/mobile_security/results/v2/

Is the base URL for version 2 of the Mobile Security Results API.

An existing stable version of an API may be updated over time, but those updates will generally be limited to adding new fields/attributes in responses, new optional inputs for requests, or new functionality (eg, new API operations or new resources).

There is one particular kind of possibly API-breaking change that is important to note – some fields in our API responses may contain a fixed set of possible values, sometimes called Enums. Although this does not happen often, Data Theorem may add new possible values to these Enums. Anyone integrating with our APIs should be aware that new values could eventually appear, and integration code should be written such that it gracefully handles unexpected values, and there should be processes in place to detect when this happens in order to update the integration.

Network Security

You should always access the API over HTTPS from https://api.securetheorem.com (or whatever endpoint the API is hosted at).

Data Formats

Response data in Data Theorem’s APIs is usually presented as JSON. If some API operation uses a different format, our documentation will explain this.

Our APIs also usually expect HTTP request bodies to be formatted as JSON, and not as application/x-www-form-urlencoded. A few of our API operations require the use of multipart/form-data, but they will be documented as such.

Dates, Times, and Timezones

Data Theorem’s APIs sometimes use dates and timestamps. These timestamps are usually formatted according to RFC-3339‘s profile of ISO8601. For example:

2020-02-26T18:25:16.664990-00:00

In general, the timezone offset can be omitted. However, if no timezone offset is included, then the timestamp is assumed to be in UTC (+/- 00:00).

In many programming languages, RFC-3339 formatting can be achieved using a time format string like %Y-%m-%dT%H:%M:%S.%f, although this lacks the timezone offset. In Python, this format can be achieved using the datetime.datetime.isoformat method, and there are many JavaScript libraries that support this format as well.

Rate Limiting

There is no rate limiting enforced at the moment, but we may add a per-day limit later if needed.

Authentication and Authorization

Data Theorem’s APIs require an API Key for authentication. There are two distinct kinds of API Keys:

  • The specialized Upload API Key, which is used with the Mobile Security DevOps API.
  • Standard API Keys, which are used with Data Theorem’s other APIs, and can also have their level of access configured.

Upload API Key

The Upload API key is a special API Key that is used for accessing the Mobile Security DevOps API. It associates the supplied mobile app builds/files and supplementary data with your organization.

This special API key can be found at https://www.securetheorem.com/sdlc/api_access. All users with access to your organization’s account can access this key so that they can integrate their CI/CD pipelines for your organization’s mobile apps. Note that the Upload API Key does not grant any other access to your organization’s data.

The following screenshot shows where you can find the Upload API Key:

The Upload API Key can be found on the Scan Via CI/CD page in the Data Theorem portal

Standard API Keys

Data Theorem’s other APIs require a standard API Key. These API Keys can be managed and accessed by Manager users in Data Theorem’s portal at https://www.securetheorem.com/sdlc/results_api_access. If you are unable to access that page, you will need to ask a Manager user in your organization to set up an API Key for you.

Each API Key will need to be granted access before it can access one of Data Theorem’s APIs. For most APIs (except the Mobile Security DevOps API) this can be done by simply enabling or disabling access to that particular API. However, for the Mobile Security Results API, an API Key can be granted a finer degree of access; it can have access to all mobile apps in your organization, or it can be configured to only have access to specific mobile apps, and their associated data.

Managers: To create a new key, click on the “Create API Key” button within the “API Access” section of the SecDevOps page. Next, configure the API key on the Create API Key page. The name field allows an API key to be easily identifiable. The rest of the parameters will have to be set depending on the use case of the API key. When the API key is saved, the Edit API Key page will load with the actual generated key.

The following screenshot shows an example of an API Key that has been configured to have access to just a few mobile apps:

Example of an API key that has access to just a few mobile apps

Using API Keys

Authentication is done by passing the API Key as part of the Authorization header, within all requests sent to the API you are interacting with. For example, the Authorization header may look like:

1
Authorization: APIKey 1234567890abcdefgh=

For example, you can use the API Key with curl in order to access the Mobile Security Results API with the following command (replace the fake API Key string with your actual API Key secret):

1
curl -H "Authorization: APIKey 1234567890abcdefgh=" -X GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps

Troubleshooting Authentication and Authorization

If there is a problem with authentication, Data Theorem’s APIs return 4xx HTTP status codes. The following explanations may help you understand what the problem is:

  • A response of 401 Unauthorized indicates that the request was not authenticated. Either you omitted an API Key, the Authorization header was not formatted correctly, or there is a problem with the API Key string you submitted.
  • A response of 403 Forbidden indicates that the request was authenticated, but the API Key does not have permission to call the requested API operation. Most likely, your API Key does not have access to the API. See the section above about Standard API Keys for information on granting the API Key access.
  • A response of 404 Not Found may mean a resource does not exist, but it may also be returned if a particular resource exists but the API Key does not have permission to access it. Currently, this only applies to resources hosted through the Mobile Security Results API related to a mobile app that a given API Key does not have access to.