ATO

This page details how an authorized studio organization can use the ATO Helper Plugin

Before you can use this API, you must:

1. Register your organization in MOTAR Studio.

2. Obtain ATO plugin developer permissions from a MOTAR administrator.

3. Create and configure your ATO plugin in MOTAR Studio.

4. Activate your plugin in MOTAR Studio.

Starting an ATO Request

When an app owner starts an ATO request for their app, the MOTAR API will send the following data to the endpoint you specify in your plugin's configuration.

{
    "requestId": ID, required,
    "companyId": String, required,
    "companyName": String, required,
    "companyPhone": String, optional,
    "requestingUserFirstName": String, required,
    "requestingUserLastName": String, required,
    "requestingUserEmail": String, required,
    "appName": String, required,
    "packageName": String, reqiured,
    "reportUri": String, optional,
    "status": String, required,
    "completed": Boolean, required
}

Note that for an initial request, many of these fields will not be set. Here is an example JSON document for a brand new request.

{
    "requestId": "961675a32173cd4c377fd4d6",
    "companyId": "5cab8f483d27cf0015990808",
    "companyName": "Dynepic",
    "companyPhone": null,
    "requestingUserFirstName": "Adam",
    "requestingUserLastName": "Reiter",
    "requestingUserEmail": "[e-mail]",
    "appName": "My App",
    "packageName": "My App ATO Package",
    "reportUri": null,
    "status": "not-started",
    "completed": false
}

This JSON structure will be sent in a POST request, along with a Basic authentication header generated using your plugin's client ID and client secret. You should verify the token is valid before accepting the request. You can also verify that the request originated at the api.motar.io domain for additional security.

Any "status" field can have the following values:

• not-started

• in-progress

• action-required

• under-review

• completed

Handling MOTAR Studio Handoff

After a request is started, MOTAR Studio users belonging to the organization that owns the app can begin or continue the ATO process using your ATO application. Technically, this is handled via the MOTAR Single-Sign On (SSO). To support this handoff, you must configure a redirect URI for your plugin. When the user completes the SSO login, they will be redirected to your plugin's redirect URI, along with an authorization code. Your ATO application should read this code and use to generate an authorization token, which can then be used for further API calls. For more information, see Authentication.

After the SSO redirect, the unique identifier for the ATO request will be in the state parameter. This is the requestId that can be used in the API calls below.

APIs For ATO Applications

These APIs are available for managing ATO requests.

Update Request Status

POST https://api.motar.io/plugin/v1/ato/status

Update a request's overall status.

Headers

Name	Type	Description
Authorization	string	Authorization token generated by SSO.

Request Body

Name	Type	Description
cancellable	boolean	Whether or not the user can cancel this request in MOTAR Studio.
status	string	A new status for the request.
complete	boolean	Whether or not the request is complete.
requestId	string	Request ID that was created when the ATO request was initiated.

200 Returns the ATO request document.

{
    "requestId": ID,
    "companyName": String,
    "companyPhone": String,
    "requestingUserFirstName": String,
    "requestingUserLastName": String,
    "requestingUserEmail": String,
    "packageName": String,
    "appVersion": String,
    "reportUri": String,
    "status": String,
    "completed": Boolean
}

Create Alert

POST https://api.motar.io/plugin/v1/ato/alert

Creates an "alert" that will display in the ATO package progress view in MOTAR Studio.

Headers

Name	Type	Description
Authorization	string	Authorization token generated by SSO.

Request Body

Name	Type	Description
requestId	string	ID of ATO request to which this alert pertains.
title	string	A title for this alert.
text	string	Text to display in the body of the alert.
providerId	string	An ID used internally by your application.
status	string	Alert status.
type	string	Alert type. Allowed values are "info", "success", "warning", and "error". Defaults to "info".

200

Handling Adding or Removing App Distributions

In MOTAR Studio, app developers can add or remove distributions from their ATO package. These distributions represent a version of the application that they wish to include in their ATO package. Your API should be configured to accept these requests and you should configure your plugin in MOTAR Studio with an endpoint to receive them.

The following JSON document will be sent to your configured endpoint when the user makes a distribution change.

{
  "requestId": String,
  "companyId": String,
  "distributions": [{
    "version": String,
    "platforms": [
      {
        "name": String,
        "devices": [String]
      },
      ...
    ]
  }, ...]
}

Adding or removing a distribution will trigger the same endpoint. Whatever is sent in the "distributions" array represents the current state.