App registration

Overview

The Seismic developer platform enables our developer and partner communities to interact with and extend the Seismic platform.

Our developer portal houses all of Seismic's technical documentation regarding our public APIs, public UI components, and other developer tools. This documentation is continually updated as we are actively evolving our public offerings.

Apps are the mechanism by which developers can interact with Seismic's developer tools.

App registration is the first step in the process to define an app. These are registered in the (App Registration Portal) Follow the directions below to understand the process of defining and registering an app.

After you have registered an app, the next step is to have a Seismic Admin (Premium user with Full Access) enable your app within your tenant. Apps are enabled and managed in your Seismic tenant under Admin > System Settings > My Apps

Defining an app

A developer can create a wide variety of types of apps in Seismic. The only requirement is that an app with API access must define an authentication method (including assigning scopes to your app).

The starting point to register an app is App Registration.

📘

Example App types

• An app with an extension
• An app with API access
• An app with an event subscription

App Registration

Registering an app requires the developer to complete 5 sections for the app:

1. Basic information
2. Authentication
3. Events
4. Callbacks
5. Extension Points

These sections can be modified after the app exists.

Versioning

App Registration handles all versioning on behalf of the developer.

Versioning supports 3 levels (e.g. 1.0.0)

• Level 1: Catalog versioning (if you submit to catalog this major version increments else its always 0)
• Level 2: OAuth scope changes (including auth method)
• Level 3: Extensions, callbacks etc. (not meta data about the app)

Distribution

Apps can be distributed several different ways:

• Local Apps: Apps defined for a specific tenant based on the app registration association are considered to be local apps. Local apps are automatically installed within a tenant but can only be deleted from within app registration. Local apps are still required to be enabled within a tenant on the Manage Apps page.
• Private Apps: Apps can also be directly distributed to another tenant as a private app. Private apps are linked directly to the source app, though they are still required to upgrade if an update is pushed.
• Public Apps: Public apps can be installed directly from the app catalog on the 'Browse Apps' section of the Manage Apps page. Public apps represent Seismic-approved apps that are built and managed by Seismic or an approved 3rd party.

📘

Distribution links

Distribution links can be provided directly to Seismic admins to install an app. If an app is installed from a distribution link it can be uninstalled using the remove app option within the Manage Apps page.

To locate an app distribution link navigate to the bottom of basic information within your app.

Catalog

📘

Submission process

Submission to the app catalog from app registration is coming soon! In the meantime, please reach out to your Seismic representative if you believe your app should be included in the catalog and we will work to review that request.

Signing secret

App registration supports the generation of a signing secret that can be used to validate payloads that originated from Seismic.

All applications that want to receive callbacks (install, uninstall, enable, disable and update) or use the Configuration UI extension will need to generate a signing secret because Seismic uses this secret to sign payloads. We will use this to encrypt the JSON payload we post to you. You can then ensure that the calls are in fact coming from Seismic.

The signature is calculated using a HMAC algorithm using SHA265. The signature is sent with each request in the request header. The header key for the HMAC is x-seismic-signature.

The recipient service should use the secret to validate that the payload HMAC using SHA256 and compare it with the x-seismic-signature sent in the request header. This same approach can also be used by external services (like content uploader) to send requests to Seismic using the extensions platform.

The secret is issued to an app and is not tenant specific.

❗️

Signing secret regeneration

If the signing secret is leaked, it can be regenerated in App Registration. The signing secret is common for all versions of the app - published and unpublished.

[HttpPost("config")]
public async Task<IActionResult> Configuration()
{
    using (var memoryStream = new System.IO.MemoryStream())
    {
        await this.HttpContext.Request.Body.CopyToAsync(memoryStream);
        var key = System.Text.Encoding.UTF8.GetBytes(signingSecret); // the app's signing secret

        using (var hmac = new System.Security.Cryptography.HMACSHA256(key))
        {
            var body = memoryStream.ToArray();
            byte[] bodyHash = hmac.ComputeHash(body);
            var computed = System.BitConverter.ToString(bodyHash).Replace("-", "");
            var incoming = this.HttpContext.Request.Headers["x-seismic-signature"];

            var bodyString = System.Text.Encoding.UTF8.GetString(body);
            var json = Newtonsoft.Json.Linq.JToken.Parse(bodyString);

            var requestTime = json.Value<DateTime>("timestamp");

            // Validate signatures match and request not more than 2 minutes old.
            if ((incoming != computed) || DateTime.UtcNow - requestTime > TimeSpan.FromMinutes(2))
                return Unauthorized();

            var appId = json.Value<string>("appId");
            var appName = json.Value<string>("appName");
            var tenantId = json.Value<string>("tenantId");
            var tenantName = json.Value<string>("tenant");
            var version = json.Value<string>("version");
            var userId = json.Value<string>("userId");
            var userEmail = json.Value<string>("userEmail");
            var language = json.Value<string>("language");

            return View(new { appId, appName, tenantId, tenantName, version });// or serve the config page in some other way.
        }
    }
}

Additional information regarding the sample code:

• Read the request body as is, without any transformations or parsing, as bytes.
• Computes its hmac signature using the app's signing secret.
• Parse the body as a json and read the timestamp.
• Execute validations.
• The computed signature matches the incoming signature in the header.
• The request is no more than 2 minutes old.
• Return an error if validations fail.

All request payloads also carry a timestamp object. It is recommended that all apps verify requests are no more than 2 minutes old. Not building this check may lead to request replays. All timestamps are in yyyy-MM-ddTHH:mm:ssZ format and are based on UTC.