Create Your App

After registering with SOA Software Open, your next step is to create an application project in order to get access to our APIs. You can use the Add New App function to do this easily. For each app you create, we'll provide you with an App ID which you will use in your code to authenticate your app with us at runtime. After completing this step, you can then submit a request to license an API.

App Creation

How does an app consume APIs?

How do I create a new app in SOA Software Open?

How do I manage app visibility?

App Security

How do app credentials work?

How do I generate a shared secret?

How do I configure OAuth credentials?

How do I regenerate a shared secret?

How do I view a shared secret?

How does public key integration work?

How do I select a tool for generating a Certificate Signing Request (CSR)?

How do I import a certificate signing request?

How do I export credentials?

How I remove app credentials?

View Apps

Where can I get a quick view of all my apps?

App Versioning

How does app versioning work?

How do I create a new version of my app?

How do I delete app versions?

How do I edit app version information?

App Management

How do I cancel an API Access Request?

How do I disconnect my app from an API?

How do I delete my app?

App Creation

How does an app consume APIs?q

After you create an app, several tasks must be performed so the app can consume an API.

Task	Description
Identify APIs	First, you must identify APIs you would like to add to your app. This can be done by performing a search via the Search Menu and browsing the APIs on the APIs > Details page of each API.
Provision App with Authentication Key	Next, you must provision the app with an authentication mechanism. When you create your app, an App ID and Shared Secret are automatically assigned. If you would also like to add a certificate to your app, you can generate a Certificate Signing Request and upload it. See How do app credentials work?
Add APIs and gain access to Sandbox environment	After targeting APIs you would like to add, the next step is to submit an API Access Request to license an API and gain access to the app sandbox or production environment. This task is performed using the API Access Wizard accessible by clicking the Access link on the APIs > Details page of a selected API. Here you select the APIs which you would like to license. For APIs that require license agreement acceptance, you must review and agree to the terms of one or more license agreements before access will be granted. The Policies section allows you to select one or more SLA policies to be used for monitoring API performance and quota management. Access to sandbox or production environments is, in most cases, automatically approved. The Sandbox or Production endpoints are available and visible in the My Apps > APIs page.
Build App	The next step is to build your app and integrate the Sandbox Endpoint, App ID, and Shared Secret (or PKI-based Public Key) available in the App Details > Security section. See App Security for more information.
Complete App Testing in Your Sandbox	Set up simulated user accounts and data in your sandbox and test your app.
Request Production Approval	When you are finished testing and ready to gain access to our production environment, you request production access using the API Access Wizard. Upon approval, you will be ready to go live and make calls to our production environment.
Update Application with Production Endpoint	When the status of your Production Endpoint is "Activated" you must then update your app with the Production Endpoint URL.
Switch to Production	After the Production Endpoint is updated in your app, you can select Switch to Production.

How do I create a new app in SOA Software Open?

To add an app:

From the Plus Menu, select Add a New App. The Add App Info page displays.

To configure your app, specify the following information:

Chart Name	Description
App Name	A text box that allows you to specify a descriptive name for your app. When developing an app naming convention, note that your initial app name will be automatically assigned as the App Name for subsequent versions (e.g., Version 1.0) and will be "App Name [App Version Name].
Version ID	A text box that allows you to specify the app version name. This name will display on the Overview section of the My Apps > Details page.
Tags	A text box that allows you to enter tags are keywords that can be used to search for posts or tickets in the App or API Boards.
Visibility	A radio button that allows you to configure whether you would like your app to be public or private.
App Description	A text box that allows you to specify a detailed description of your app.
Version Description	A text box that allows you to specify a detailed description of your app version.
App Website	A text box that allows you to specify a URL for the website associated with the app you are defining.

On the Add App Info page, specify the the App Name, Version ID, Tags, Visibility (Public/Private), App Description, Version Description, and App Icon. All information here displays on your customer-facing App description.
- You can optionally upload an icon to uniquely identify your app. See How do I upload and crop icons?
  for more information.
- Your App description should include marketing, functional, and use case information.
After completing your entries, click Save. The app information is saved and posted to the App Details page. If you would like to update your app information, click Edit.
To exit this operation, click Cancel.

How do I manage app visibility?

When you create an app using Create a New App, you can control whether visiblity of the app is Public or Private via the "Visibility" option. You can change app visibility based on your requirements using the Edit function on the App Details page.

A public app is visible to all individuals that use the SOA Software Open site, is searchable, and displays in the All Apps search filter.
A private app is visible to the creator, in the My Apps search filter, and to individuals that are members of the app team.

App Security

How do app credentials work?

Authentication gives your app the ability the know the identity of an application user, and to interact with API data. Before configuring security for your app, you must first identity the protocol that is required by an API for performing authentication and authorization. Selection is based on the protocol supported by the API (e.g., plain text App Id, signed header with x.509 or a shared secret, or OAuth (1.0, 1.0a, or 2.0), and the configuration of the Policy Manager "API Consumer Application Security Policy" that is assigned to API the application will be interacting with. The credential approach configured in the app must match the protocol supported by the API - as defined in the "API Consumer Application Security Policy."

To authenticate your app when placing API calls, you must include your App ID and either a Shared Secret or your Public Key for PKI-based authentication (in the form of a CSR).

A Shared Secret can be used for OAuth 1.0, 1.0a, and 2.0 if you are using Implicit, Resource Owner Password Credentials, or Client Credentials grant types. If you are using Oauth 2.0 configured with the "Authorization Code" Authorization grant type, you must use the Edit OAuth Details function in the App Details > Security Credentials section to configure the "Redirect URL" and "Application Type."

The Security section of the App Details page includes Shared Secret , Public Key, and OAuth options for generating the credentials required to authenticate your app with our sandbox and production systems. For assistance in determining the security credentials method that best suits your needs, see App Security.

When an app is initially created using the Add a New App function, a shared secret is generated by default and can be viewed in the Security > Shared Secret section by selecting Click to View. You can use the Regenerate Key option to issue a new shared secret.
If you would like to use PKI-based encryption, you can use the Public Key option. The Import CSR function allows you to upload a Certificate Signing Request (CSR) with your public key embedded. After you have uploaded the CSR, the Certificate Authority associated with SOA Software Open generates a certificate and associates the certificate with your app. The Remove Credentials and Export Credentials functions are now available.
For OAuth 2.0 using the "Authorization Code" Authorization Grant type, use the Edit OAuth Details function and specify the "Redirect URL" and "Application Type." The redirect option is used to specify the address of the authorization server and specify whether the application type is confidential or public.
Please note that each version of your app requires a separate set of security credentials.
Also note that you will need to obtain access to an API and you must configure credentials correctly in order to make a successful call to the API sandbox or production endpoint.

How do I generate a shared secret?

When you initially create an app using the Add a New App function, a shared secret is automatically generated. You can regenerate or view the shared secret in the Security > Shared Secret section of My Apps > App Details by selecting Click to View.

How do I configure OAuth credentials?

To configure credentials for OAuth versions 1.0, 1.0a, and 2.0 (with Implicit, Resource Owner Password Credentials, or Client Credentials grant types, see How do I generate a shared secret?

To configure credentials for OAuth versions 2.0 configured with the "Authorization Code" Authorization grant type:

Navigate to App Details > Security.
Click Show OAuth Details. The "Redirect URL" and "Application Type" currently assigned to the app displays.
To update the information, click Edit. The Edit OAuth Details page displays.
In the "Redirect URL" field, specify the URL address of the authorization server that the resource owner will be redirected to.
In the "Application Type" field, specify whether the application is Public or Confidential.
Click Save to commit your changes.
For information on testing OAuth authorization of your app and sending a request, see How do I test authorization of my app with OAuth using the Dev Console?

How do I regenerate a shared secret?

If for any reason it becomes necessary to reissue the shared secret, you can use the Regenerate Key function.

To regenerate a shared secret:

Navigate to My Apps.
- Select the App Name on the summary listing. The App Details page displays.
- Select an app version from the Current Version drop-down menu.
In the Security > Shared Secret section, click Show Keys to display the key generation options.
Click Regenerate Key. The shared secret is reissued and the Shared secret updated message displays. Use Click to View to display the new shared secret key.

How do I view a shared secret?

To view the current shared secret:

Navigate to My Apps.
- Select the App Name in the summary listing. The App Details page displays.
- Select an app version from the Current Version drop-down menu.
In the Security section, click Show Keys to display the key generation options.
Click Click to View to display the current shared secret.

How does public key integration work?

If you use the Public Key option, you must import a Certificate Signing Request (CSR).

You can generate your CSR using any online CSR generator command tool.
You provide the Common Name, Organization, Organization Unit, City, State, Country, and Key Size and the tool creates both your private key and certificate signing request (.key and .csr files).
You then use the Import CSR function of SOA Software Open to upload the CSR for the current app.
The CSR and the Certificate Authority (CA) associated with the SOA Software Open site are used to generate the certificate for the app.

How do I select a tool for generating a Certificate Signing Request (CSR)?

There are a variety of different tools you can you can use to generate a Certificate Signing Request (CSR). For example, Keytool and OpenSSL are popular CSR generation tools.

Perform an online inquiry using search strings like tools, certificate signing request or How do I generate a certificate signing request externally?
The results will provide all the information you need to select a tool that will work for you and meet your requirements.

In the context of SOA Software Open the process is as follows:

Generate a public and private key using an external tool. Use your private key to sign your API call. Use your public key to generate the Certificate Signing Request.
Generate the Certificate Signing Request (CSR) using an external tool as well.
Import the CSR into SOA Software Open. This is done using the SOA Software Open Import CSR function. See How do app credentials work?
Obtain a copy of the generated certificate. This is done using the SOA Software Open Export Credentials function. See How do I export credentials?

How do I import a certificate signing request?

To import a certificate signing request (CSR):

Navigate to My Apps.
- Select the App Name on the summary listing. The App Details page displays.
- Select an app version from the Current Version drop-down menu.
Navigate to the Security section and click Show Keys to display the key generation options. In the Public Key section, click Import CSR. The CSR Import Details pop-up displays.
Click Browse and navigate the directory structure to target your certificate file.
Select the file and click Save.
The Certificate Signing Request (CSR) is imported and the certificate is generated. If the CSR you are attempting to upload is expired or invalid, you will receive an error message.

How do I export app credentials?

After the Certificate Signing Request is imported and the certificate is generated, you can download the app certificate.

To download the app certificate:

Navigate to My Apps.
- Select the App Name on the summary listing. The App Details page displays.
- Select an app version from the Current Version drop-down menu.
Navigate to the Security > Public Key section. Click Export Credentials. The Opening dialog box displays.
To save the certificate file, click the Save file radio button.

How do I remove app credentials?

If it becomes necessary to change your app security credentials (e.g., certificate is nearing expiration date, your private key becomes compromised, etc.), you can upload a new Certificate Signing Request and regenerate the certificate for your app. This is accomplished by removing the current set of credentials. You can then use the Import CSR function to import a Certificate Signing Request (CSR). To do this:

Navigate to App Details > Security.
Click Show Keys to display the key generation options. In the Public Key section,
In the Public Key section, click Remove Credentials. The credentials are removed.
Use the Import CSR function to import a new Certificate Signing Request (CSR). See How do I import a certificate signing request?

View Apps

Where can I get a quick view of all my apps?

The My Apps page displays a summary listing of apps you have defined and are currently following. After you have logged in, the page is accessible by clicking the My Apps Quick Filter Icon and includes the following functions:

Function Name	Description
Add a New App	If you have not defined an app, the Learn More icon displays and directs you to the Add a New App function. This function can also be accessed via the Plus Menu.
Explore Apps / Apps I'm Following /	If you are not currently following any apps, the Explore Apps icon displays and directs you to a listing of Apps currently defined in SOA Software Open that you can review. You can click Follow on apps you find interesting and they will display in the Apps I'm Following section.
Search	The Filter panel allows you to sort your app listing using a selection of sort criteria including Type, Sort By, and Tag or Keywords.
View Details	You can click the App Name to view the Details page.

App Versioning

How does app versioning work?

During the app development process, the need may arise where you require different app versions. For example:

You may want to have one app that is strictly a support/testing version, and another that is a production version, or you may want to have variations of your app that utilize different APIs.
You may also want to separate usage monitoring, discussions, and ticket management by app version.

To facilitate this, the My Apps section includes app versioning functionality that allows you to create a new instance (i.e., version) of an existing app.

App Version Composition

When you create your first app (i.e., Version 1.0):

You define an App Name and a system generated Version ID is assigned.
A Current Version menu item is displayed on the My Apps title bar.

Create New App Version

After creating your Version 1.0 app, you can then create an app version using the + Version function accessible via the App Details page.

An App Version name is composed of the Version ID (i.e., App Name).
The Version ID is accessible via the Current Version menu. You can also assign Version Notes and Tags to further identify the app version definition.
The Version ID can be modified using the Edit function on the App Details page.
After creating your app version, you can then assign credentials, submit an API Access Request, and perform app management activities.

Note: When the app version is created, SOA Software Open also auto-generates an internal App ID. This App ID is what you use in SOA Software Open API calls. Refer to the App Security topic for more information on using the App ID in SOA Software Open API calls.

Viewing App Versions

You can navigate to an app version by selecting it on the Current Version menu.

Team Management

In My Apps, Team Member assignments apply to ALL apps versions. A unique set of Team Members cannot be assigned to a specific app version.

App Management

App versions can be managed using a variety of different tools available in the App Details page.

How do I create a new version of my app?

To create a new app version:

Navigate to My Apps > App Details for the app you would like to create a version for.

Select + Version. The Edit App Info page displays. The following information displays:

Chart Name	Description
App Name	A read-only field that displays the descriptive name for your app.
Version ID	A text box that allows you to specify the app version name. This name will display on the Overview section of the My Apps > Details page.
Tags	A text box that allows you to enter tags are keywords that can be used to search for posts or tickets in the App or API Boards.
App Description	A read-only field that displays your app description.
Version Description	A text box that allows you to specify a detailed description of your app version.

Specify the Version ID, Tags, and Version Description, and click Confirm to commit your changes.

How do I change the version ID of an existing app?

The "Version ID" (i.e., name) of the app version can be changed using the Edit function on the App Details page. See How do I edit app version information? for instructions.

How do I delete app versions?

Deleting an app version is standard app management task. See How do I delete my app? for details.

How do I edit app version information?

App version information can be changed using the Edit function in the App Details page. To do this:

Navigate to My Apps and select the app that includes information you would like to update. The App Details page displays.
Select the app version from the Current Version drop-down menu.
Select Edit. The Edit App Info popup displays.
Update the version information (Version ID, Tags, Version Description) and click Confirm to commit changes.

App Management

How do I cancel an API Access Request?

If you would like to cancel the API Access Request after it is submitted, you can post a comment to the API Access Request post requesting that the API Administrator cancel the request. See How do I ask or answer questions relating to a post or ticket?

How do I disconnect my app from an API?

You can disconnect your app from an API it is consuming in Sandbox or Production environments using the Cancel or Suspend functions in My Apps > APIs . See How do I update approved API access requests?

How do I delete my app?

You can delete an app version on the App Details page:

To delete an app on the App Details page:

Navigate to My Apps and select the app version you would like to delete on the Version menu.
Select - Version.
The "Are you sure you want to delete this application version?" confirmation message displays.
Click OK to delete the app, or Cancel to exit the operation.