Arlo

REST Auth API: OAuth 2

This article documents how to use Arlo's implementation of OAuth2 with your application.

This page covers the general supported features, details of how to create and manage information about OAuth clients in your application, sample clients, and how to handle OAuth HTTP error responses.

Before implementing any OAuth flows with your application, make sure you review our guidelines on how to manage access token caching.

For a quick start reference, see our OAuth API Usage article.

Skip to:

RFC reference

The canonical OAuth 2.0 RFC can be found here.

Supported features

The only supported flow at this time is the authorization code grant flow. For specific usage and endpoint details, see the OAuth API usage article.

The tokens issued by the API have a limited life (expiration), so must be periodically refreshed. We do not provide access to lifetime tokens.

Specifically, Arlo's implementation of OAuth supports the following features:

Managing clients

Creating clients

To create an OAuth client, you first need to Register a developer account with us.

If you already have an account, you can use the OAuth clients section of our Developer site to create and manage your OAuth client details and issued tokens.

Managing client credentials in your application

The OAuth standard requires that the client application (your application) must store certain information with varying levels of sensitivity.

In discussing the levels of sensitivity, we use the following classifications:

  • Public: Public information
  • Internal Use: Confidential business information
  • Confidential: Information that customers consider confidential
  • Sensitive: Personal and Private Information (PII), information that the law considers confidential
  • Highly Sensitive: Encryption keys, server secrets, staff/admin passwords

The table below summarizes the OAuth-related data that your application must store, with associated sensitivity classifications.

Information Classification Storage requirements
Client ID Internal use Secure
Client secret Highly sensitive Secure, limited access, recommend encrypted storage
Access tokens Highly sensitive Secure, limited access, recommend encrypted storage
Refresh tokens Sensitive Secure, limited access, recommend encrypted storage

Caching access tokens

It is important that your application minimises the number of calls to our OAuth APIs as much as possible. In particular, your application should parse the expires_in access token field to determine the lifetime of the token and when it will expire. You should cache it in persistent storage until that time lapses.

During the period before the token expires, the cached token details should be sufficient to use our API -- it should not be necessary to use explicit API calls to validate or refresh the token.

If one of the Arlo API resources returns a HTTP 401 or 403 OAuth error response with an invalid_token or expired_token error code, this might indicate that the resource has determined that the token is expired or is no longer valid. At this point, your code should use the OAuth APIs to refresh the token or initiate the generation of a new one.

In short, you SHOULD:

  • Parse the access tokens and determine when they will expire
  • Use cached versions of the tokens for all API requests that require authentication
  • Wait for the API to return HTTP 401 or 403 responses before making API calls to check if the token is valid or needs refreshing

You SHOULD NOT:

  • Call APIs to validate the token before every request
  • Call APIs to refresh the token if it has not expired

Sample code

As an aid to understanding the use of OAuth with our API, we have created a GitHub repo with a sample OAuth authorization code flow client, at https://github.com/ArloSoftware/apioauth.

OAuth HTTP responses

Any general API request that uses an OAuth bearer token may during its execution receive an HTTP 401 Unauthorized error. If the reason for the error is OAuth-related, the HTTP response may contain a WWW-Authenticate header with additional detail about the nature of the error.

Example

An example request with an invalid token and HTTP response with WWW-Authenticate header containing details about the issue:

GET https://demo.arlo.co/api/2012-02-01/auth/resources/contacts HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Bearer my_invalid_token
    
HTTP/1.1 401 Unauthorized
Content-Length: 0
WWW-Authenticate: Basic realm="demo", 
                  error="invalid_token", 
                  error_message="The access token is invalid"

WWW-Authenticate response header

Consistent with the specification in RFC 6750, WWW-Authenticate HTTP response header can contain these fields:

Property Description
realm The scope of the authentication (always the name of the platform).
error The machine-readable code of the error.
error_message (Optional) A human-readable description of the error, if available.
scopes (Optional) Any scopes relavant to the error. Typically included only when the error code is insufficient_scope.
Common error values

The table below lists some common error values and their details.

NOTE: When a token has expired, Arlo can return either expired_token or invalid_token errors. Your code should not rely on detecting the expired_token response alone to determine whether a refresh is required.

Error Reason Troubleshoot
invalid_request The OAuth authorization server considered the request, and found that it could not be interpreted. This is likely to be a client application error in terms of protocol use.
invalid_token The specified token could not be found, has expired, or has been revoked. A new token is required. If you have a stored refresh_token, you can make a request to refresh your access token. If you do not have a refresh token, you must start the authentication process again and obtain a new access token.
expired_token The OAuth authorization server extracted an access token from the request, but determined it had expired. The token supplied has expired. As above, if you have a refresh token, you should use it to request a new one.
insufficient_scope The OAuth authorization server extracted an access token from the request, but the scopes to which it pertained were insufficient to complete the requested operation. The token supplied does not have the scope required to execute the API call successfully. The required scope will be provided as one of the values of the WWW-Authenticate response header. A new token with the required scope (or an all encompassing scope) should be requested from the authorization server - this will often require a new round of user consent.