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.
The canonical OAuth 2.0 RFC can be found here.
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:
- Obtaining access tokens from explicit user grants using resource and scope claims
- Refresh tokens
- Token validation
- Token revocation
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.
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.
|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|
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
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
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.
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.
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"
Consistent with the specification in RFC 6750,
WWW-Authenticate HTTP response header can contain these fields:
|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.|
(Optional) Any scopes relavant to the error. Typically included only when the error code is
The table below lists some common
error values and their details.
NOTE: When a token has expired, Arlo can return either
invalid_token errors. Your code should not rely on detecting
expired_token response alone to determine whether a refresh is required.
|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
|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.|