Zebra OTA API

Developer Guide

for Automated Customer Authorization

MN-003881-01EN

ZEBRA and the stylized Zebra head are trademarks of Zebra Technologies Corporation, registered in many jurisdictions worldwide. All other trademarks are the property of their respective owners.

© 2019 Zebra Technologies Corporation and/or its affiliates. All rights reserved.

Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of those agreements.

For further information regarding legal and proprietary statements, please go to: SOFTWARE: http://www.zebra.com/linkoslegal

COPYRIGHTS: http://www.zebra.com/copyright

WARRANTY: http://www.zebra.com/warranty

END USER LICENSE AGREEMENT: http://www.zebra.com/eula

Terms of Use

Proprietary Statement

This manual contains proprietary information of Zebra Technologies Corporation and its subsidiaries (“Zebra Technologies”). It is intended solely for the information and use of parties operating and maintaining the equipment described herein. Such proprietary information may not be used, reproduced, or disclosed to any other parties for any other purpose without the express, written permission of Zebra Technologies.

Product Improvements

Continuous improvement of products is a policy of Zebra Technologies. All specifications and designs are subject to change without notice.

Liability Disclaimer

Zebra Technologies takes steps to ensure that its published Engineering specifications and manuals are correct; however, errors do occur. Zebra Technologies reserves the right to correct any such errors and disclaims liability resulting therefrom.

Limitation of Liability

In no event shall Zebra Technologies or anyone else involved in the creation, production, or delivery of the accompanying product (including hardware and software) be liable for any damages whatsoever (including, without limitation, consequential damages including loss of business profits, business interruption, or loss of business information) arising out of the use of, the results of use of, or inability to use such product, even if Zebra Technologies has been advised of the possibility of such damages. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you.

Publication Date

March 4, 2020               -01 Rev             Initial release

Introduction

This guide provides an overview of the processes used by a client application developer to integrate Zebra’s SSO based 3-legged OAuth 2.0 protocol.

IMPORTANT: If you have a problem with your equipment, contact Zebra Global Customer Support for your region. Contact information is available at: http://www.zebra.com/support.

Notational Conventions

The following conventions are used in this document:

• Bullets (•) indicate:
  • Action items
  • Lists of alternatives
  • Lists of required steps that are not necessarily sequential.
• Sequential lists (e.g., those that describe step-by-step procedures) appear as numbered lists.

Icon Conventions

The documentation set is designed to give the reader more visual clues. The following graphic icons are used throughout the documentation set. These icons and their associated meanings are described below.

NOTE: The text here indicates information that is supplemental for the user to know and that is not required to complete a task.

IMPORTANT: The text here indicates information that is important for the user to know. CAUTION: If the precaution is not heeded, the user could receive minor or moderate injury. WARNING: If danger is not avoided, the user CAN be seriously injured or killed.

DANGER! If danger is not avoided, the user WILL be seriously injured or killed.

OAuth 2.0 Overview

OAuth 2.0 uses access tokens as an authorization identifier to a client. Access tokens are obtained from an authorization server and have a shorter lifetime and fewer permissions than a user.

OAuth 2.0 defines four roles used in getting, validating, and using an access token.

• User (Resource owner)
• Client Application (Application which consumes Zebra APIs)
• Authorization Server
• Resource Server (Zebra APIs)

Developer Responsibilities

• Get authorization from a user to call Zebra APIs.
• Use the authorization in subsequent calls to protected Zebra APIs.
• Use refresh tokens to refresh an expired authorization.

Refresh tokens are credentials used to obtain new access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires.

• Revoke the authorization.

Reference

• Device flow grant type: https://tools.ietf.org/html/draft-ietf-oauth-device-flow-14
• Revoke token: https://tools.ietf.org/html/rfc7009

The client application is granted authorization using access tokens obtained from the authorization server.

Get Authorization

Use the Device Flow Grant Type to obtain access tokens for a client application.

Prerequisites

• The developer must register on the Zebra Developer Portal and obtain valid, authorized client credentials (client ID and client secret).

Step 1: Get User Code, Device Code, and Verification URL

The client application triggers an API request to obtain the user code, device code, and verification URL from the authorization server.

Request Details

URL: https://api.zebra.com/v1/user/device_authorization

Response Details

Sample Postman Request

Sample Postman Response

Error Details

Step 2: Display User Code and Verification URL

After receiving a successful authorization response, the client application must display or communicate the user_code and verification_uri to the end user, instructing them to visit the URI in a user agent on a secondary device and enter the user code. For example, the instructions might say to enter to code in a web browser on their mobile phone.

Step 3: Authorize the Client

Users must follow the login using Zebra credentials and authorize the client application.

Step 4: Get Access Token

After displaying instructions to the user, the client application must contact the authorization server to get the user’s authorization status. The client is expected to repeatedly check in a polling fashion based on the error code in the response and the interval. Once the user authorizes, the authorization server responds back with an access token for the authorization check request.

Request Details

URL: https://api.zebra.com/v1/user/token

Response Details

Sample Postman Request

Sample Postman Response

Error Details

Use Authorization

Use access tokens as an authorization token to access Zebra protected APIs. To use an access token to access a protected resource, the access token must be passed as a Bearer authorization credential in HTTP Authorization header.

Endpoint URL (assume): https://api.zebra.com/v1/ota-api/artifacts/

If the authorization server successfully validates the access token the request is proxied to backend Zebra APIs.

The developer must configure the access token validation endpoint for the respective API.

Refresh Authorization

When an access token expires, the client application must use an existing refresh token to get a new access token and a new refresh token. This ensures the Zebra API calls are not interrupted.

Prerequisites

• The developer must register on the Zebra Developer Portal and obtain valid, authorized client credentials (client ID and client secret).
• The refresh token must be valid.
• The client must be authorized to refresh the tokens.

Refresh the Access Token

To refresh an access token, the client application must make an API call to the endpoint of the authorization server token to refresh the access token.

Request Details

URL: https://api.zebra.com/v1/user/token

Response Details

Sample Postman Request

Error Details

Revoke Authorization

When a user wants to revoke their authorization over a client application or when client applications are uninstalled, the client applications must invalidate the refresh token, access token, or both tokens by triggering an API call to the authorization server.

Request Details

Sample Request