anchorIntroduction to Service Apps

Service apps enable you to request admin permission to use Webex REST APIs, reducing dependence on a single user's authorization and mitigating any associated risks to your app. Instead, the actor for the API calls is a powerful machine account provisioned in the customer's org, ensuring your business automation flows will continue to run smoothly.

Service Apps are often used for mission-critical business processes including:

• End to end provisioning of users
• Reporting dashboards for critical quality analysis
• Meeting scheduling systems
• Onboard new Webex calling users
• … and much more.

Common to such apps is that they must run continually and be independent of any single user account. In contrast, for standard Integrations, if the authorizing user leaves the company or changes passwords, the Integration may break. In addition, unlike standard Integrations, Service Apps usually request data for many users and the whole org rather than on behalf of a single user.

Service Apps do share many similarities with Integrations. The industry standard OAuth 2.0 protocol underpins both. OAuth client creation, scope selection, and authorization are happening just as they do for Integrations; however, those flows are mostly abstracted in a GUI experience for both the developer and the admins.

anchorService App Creation

Two distinct personas are involved in putting a Service App into service: the developer and the full admin.

Service App Creation: Developer Flow

As a developer, to create your Service App you need to do the following:

1. Register your Service App with Webex.
2. Request admins’ authorization (must be a Full Admin).
3. Retrieve the access and the refresh token.
4. Use the access token to make your API calls.

Register your Service App

As a developer, you primarily work in the Webex Developer Portal. Registering your Service App with Webex is easy:

1. Login to the Developer Portal and select My Webex Apps from the menu under your avatar.
2. At the top of the page, click Create a New App and then Create a Service App to start the wizard.

You'll need to provide basic information, like your service app’s name, description, and logo. This information should be user-facing since admins will see it on the Control Hub’s management page. You also need to select the scopes for your Service App. For more information on scopes, please see the Integrations app page.

NOTE: Analytics and XSI scopes do not currently work with Service Apps, and meeting scopes have limited functionality. Also, note there is a limit on the number of scopes that can be selected. This is a string limit, and the scope list is limited to around 880 characters. We ask you to carefully select these scopes. Service Apps are very powerful, and admins will be reluctant to approve too much power to these Service Apps.

NOTE: If the Service App requests Compliance Officer scopes as indicated by the spark-compliance:* prefix, the Service App must be authorized in Control Hub by a Full Admin who also has the Compliance Officer role. If you see an error "Your changes were not updated. The request was unauthorized." you most likely are not a Compliance Officer, but the app needs compliance scopes to work. For questions on this restriction, please email devsupport@webex.com.

NOTE: When a Service App works with the Join a Meeting API, the hostEmail must be provided. Otherwise, the API cannot work.

After successful registration, you will be taken to a different page containing your integration's newly created Client ID and Client Secret. The same client secret will be shown once only, so copy it and keep it safe! So far, all you have done is create an OAuth client. That’s why this process likely feels very familiar. It is the same for the Integrations app type.

Things start deviating from Integrations in the top two sections on the Service App details page: Admin Authorization and Webex App Hub submissions. To understand those sections, we must first dive into the application visibility for Service Apps, which differs slightly from Integrations. When you create your Service App, initially its visibility is private. That means only you can authorize it if you also happen to be a full admin. If you are a regular user and need an admin’s help, you must follow a different process.

Request Authorization of a Service App Within the Developer's Org

To request authorization in your own org, click Request Admin Authorization. This action makes your Service App visible in your org’s administrative tool (Control Hub), where a Full Admin can then authorize it. If you are working in a free org (usually an unpaid account), you should request a sandbox, where you can create an admin to do the authorization.

Request Authorization of a Service App in a Non-affiliated Org

To request authorization in an org that is not your own org, you need to Submit to Webex AppHub. When you do that, a manual review of your Service App with the App Hub team is initiated. You must fill in additional information including how the App Hub team can test your app, which vertical you serve, descriptions and tags shown on App Hub, landing and support pages, videos, and more. You can find more information in this supporting blog.

Retrieve the Access and Refresh the Token Pair

After your Service App is authorized, you can retrieve the access and refresh token. You use them as you do for Integrations and the same token expiration policies apply. To get the token pair, go to the Org Authorizations section on your Service Apps details page. There is a drop-down list for all the orgs that authorized your Service App. You can also search by Org Id if you know the org ID and have many authorizations.

NOTE: Searching by name is not currently supported.

Once you have identified and selected the new org’s authorization, you can copy your client secret into the provided field and retrieve and copy the access and refresh tokens for the org. If you didn’t store the client's secret previously, you can regenerate it.

If you see an error like the following, your secret wasn’t copied correctly to the clipboard. Manually select it from the field and try again.

If, on the other hand, you selected too many scopes, you will see this error message. There is no strict limit on the number of scopes. Instead, a character limit for all scopes combined, around 800, is being enforced. We ask you to carefully select your scopes, as admins will be reluctant to approve apps with scopes they think are unnecessary.

Use the Access and Refresh Tokens to Make API Calls on Behalf of the Machine Account

How you use the access token to call the Webex APIs and the refresh token to keep the access token fresh is well documented on the Integrations app page.

anchorService App Creation: Admin Flow

You have the following responsibilities as an admin who wants to use a Service App:

• Be a Full Admin (read-only, device admins, etc., are insufficient).
• Understand the purpose of the Service App, the developer's background, the scopes you are authorizing, and how your organization will use it.
• Authorize the Service App for use in your org.

Full Admin Authorization of a Service App

To authorize a service app:

1. Log in to your organization's Control Hub (https://admin.webex.com).
2. Find the Service App you want to authorize. Service Apps can be found under Management > Apps > Service Apps. If you cannot see the Service App in question, you need to ask the developer to have them submit for Admin Authorization or App Hub submission You can click the Service App and will see the service app’s description, developer info, and requested scopes.
3. When ready to authorize the Service App, click Authorize followed by Save. Your name is shown as the authorizing user in Control Hub. An entry in AdminAudit events is also created, documenting who authorized the Service App.
4. Optionally, you may also wish to inform the developer that you have authorized their Service App.

Deauthorizing a Service Apps

Any full admin in Control Hub can deauthorize a Service App. This often happens because an app is no longer needed or because of security concerns.

To deauthorize a Service App:

1. Go to Management > Apps > Service Apps and highlight the Service App. Uncheck the authorized checkbox and then click Save.
2. The machine account created during authorization is deleted, and the tokens are invalidated.