REST Auth API: OAuth 2 API Usage | Arlo Training & Event Management Software

REST Auth API: OAuth API Usage

This article documents the typical steps in the flow required to obtain an access token with OAuth, including the initial request for the code, the authorization callback and additional call to obtain a usable access token.

Also covered are the APIs for refreshing a token, and validating or revoking an existing token.

For an overview of Arlo's OAuth implementation, see our general OAuth overview article.

Skip to:

Step 1: Requesting an authorization code
Step 2: Handle the user's authorization decision (callback)
Step 3: Request an access token from Arlo
Step 4: Use the access token in API calls
Refreshing the access token
Validating an access token
Revoking an access or refresh token

Step 1: Requesting an authorization code

Add a link or button in your application that sends the user to the following URL:

/{platform_name}/oauth/connect/authorize

where {platform_name} is the name of the platform.

You must include the following parameters (which must be URI encoded):

Parameter	Description
client_id	The unique identifier you obtained when you registered your application with Arlo.
response_type	The only supported response type is `code`.
scope	A space-separated list of scopes that control access to the oauth endpoints. A typical set of scopes is: `openid` (required) `profile` (required) `offline_access` (strongly recommended, as it allows for token refresh) `read` `write` (required only if you plan to update data in the API) `all_claims` (provides access to all general resource endpoints)
state	(Recommended) An opaque string that Arlo will echo back on the token response. We recommend you put a random string in this parameter that you save for every authorization request so that you can correlate/validate every callback with a legitimate authorization request. It is up to your application code to ensure that any echoed `state` matches a known value.
redirect_uri	The URL that Arlo should use to send the user's decision to grant access to your application. The URL has be absolute and not relative. It also has to be secure (https).

Example

Example GET request for requesting authorisation, including a state parameter:

GET https://demo.arlo.co/oauth/connect/authorize?client_id=MeWALA744chp8E7GEPDeElPzc8y8hNrG
    &response_type=code
    &scope=openid+profile+offline_access+read+all_claims
    &redirect_uri=https://myapp.example.org/oauth/arlo/callback/
    &state=mebnpJ49AnMwDv HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate

Step 2: Handle the user's authorization decision (callback)

The callback URL you provided in step 1 will be invoked with a HTTP GET with parameters indicating what the user decided (whether to authorise your application or not).

Access granted callback

If the user decided to grant access to the application, the redirect URL contains an authorization code string parameter, and optionally an echoed state parameter if one was provided with the original request.

Example:

https://myapp.example.org/oauth/arlo/callback/?code=4cfc8af8a1cd99ecdcf090dafea14632&state=mebnpJ49AnMwDv

Note that authorization codes have limited use period of several minutes and should not be stored. The code should be used in the next step of the process as soon as it is issued.

Error callback

The redirect URL will be invoked with an error code when:

the user explicitly denied access to the application
the authorization request was not valid

If a state parameter was provided with the original request, it will be included in any error callback.

Example:

https://myapp.example.org/oauth/arlo/callback/?error=access_denied&state=mebnpJ49AnMwDv

Common error codes and troubleshooting:

Error	Reason	Troubleshoot
access_denied	The user or server denied the access request.	There may be an issue with the scopes your application is requesting. This is a user-driven error code so there is limited opportunity for technical troubleshooting.
invalid_request	The authorization request contained an invalid or missing parameter.	Check that all required URL parameters are included as per Step 1, particularly the `scope` parameter.
invalid_scope	The authorization request contained an invalid or malformed `scope` parameter value.	Ensure this parameter refers to only supported scopes, that the scopes are separated by spaces (not commas), are lowercase, and that the whole parameter value is URI encoded.

Step 3: Request an access token from Arlo

If your application received an authorisation code in the previous step, you need to make a call to exchange this temporary code for an access token.

To get an access token, make a POST request to the following endpoint:

/{platform_name}/oauth/connect/token

where {platform_name} is the name of the platform. The response from this request will be a JSON token.

You must include the following parameters in the request (which must be URI encoded):

Parameter	Description
client_id	The unique identifier you obtained when you registered your application with Arlo. We recommend you put this in the `Authorization` HTTP header instead of the content body.
client_secret	The secret you obtained when you registered your application with Arlo. We recommend you put this in the `Authorization` HTTP header instead of the content body.
grant_type	Must have the value `authorization_code`
code	The temporary authorisation code you received when the user granted your application access.
redirect_uri	A reference to the same `redirect_uri` string used in step 1. This is used for security purposes to verify the request.

Request using credentials in Authorization header

The preferred method of exchanging the client secret is in the HTTP Authorization header, rather than including these in the HTTP POST body.

The header format must be client_id:client_secret, Base64 encoded.

For example, the header for a client ID 12345678 and secret ABCDEFGH would be

Authorization: Basic MTIzNDU2Nzg6QUJDREVGR0g=

Example request

An example token request (with the client_id and client_secret in the Authorization request header)

POST https://demo.arlo.co/oauth/connect/token HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic MTIzNDU2Nzg6QUJDREVGR0g=
Content-Type: application/x-www-form-urlencoded
Content-Length: 214

grant_type=authorization_code&code=4cfc8af8a1cd99ecdcf090dafea14632&redirect_uri=https://myapp.example.org/oauth/arlo/authcallback/

Token response structure

A successful request will return a JSON object (a JWT) that you should parse and securely store.

{  
  "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE...ImEzck1VZ0",
  "access_token":"d5382c0000a5821280de0da33f7c0f01",
  "refresh_token":"2da9a39cd60848d88aa7a7c4dbf62086",
  "expires_in":3600,
  "token_type":"Bearer"
}

The response JSON structure has the following fields:

Parameter	Description
id_token	Base64-encoded JSON containing claims that describe the authenticated identity. Generally you will not need to process this field beyond storing it.
access_token	A unique identifier that you should use in subsequent HTTP requests.
refresh_token	(Optional) A unique identifier that you should use when you want to refresh the access token (before or after it expires). This field is only included when the `offline_access` scope was specified in the original request at Step 1. Token refresh is not supported if this scope isn't requested.
expires_in	The time (in seconds) that the access token remains valid for. Use of the token beyond this period will result in HTTP 401 or 403 responses. If you need to use the token beyond this period, you can request a refresh if you have a valid `refresh_token`. Otherwise you will need to start the authenticate process again to get a new access token.
token_type	The type of the token. Always `Bearer`.

Follow our token caching guidelines and save this token to persistent storage. Use the token until the API returns a HTTP 401 or 403 response before attempting to refresh it.

Step 4: Use the access token in API calls

Your application can use the access token in subsequent Arlo API calls for the lifetime of the token. Ensure you cache the token according to our token caching guidelines.

Include the token in the Authorization HTTP request header. For example, if your token is d5382c0000a5821280de0da32f7c0f01:

Authorization: Bearer d5382c0000a5821280de0da32f7c0f01

Example

Example requesting a Contact resource using an issued OAuth token:

GET https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/562/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Authorization: Bearer d5382c0000a5821280de0da32f7c0f01

Refreshing the access token

Access tokens issued by Arlo have a limited lifespan, and eventually expire after the expires_in duration of the token elapses.

Once a token expires, requests that continue to use it will fail with HTTP 401 or 403 responses. If your application receives one of these responses, you may use the API to refresh the token provided your original request included the offline_access scope, and you saved the refresh_token string from the token response. You cannot use this endpoint if you do not have a valid refresh_token string.

To refresh an access token, make a POST request to the following endpoint:

/{platform_name}/oauth/connect/token

where {platform_name} is the name of the platform. The response from this request will be a new JSON token.

You shouldn't need to call this API frequently. Follow our token caching guidelines and wait for a HTTP 401 or 403 response for a general API request before using this API to refresh a token if it has expired.

You must include the following parameters in the request (which must be URI encoded):

Parameter	Description
client_id	The unique identifier you obtained when you registered your application with Arlo. We recommend you put this in the `Authorization` HTTP header instead of the content body.
client_secret	The secret you obtained when you registered your application with Arlo. We recommend you put this in the `Authorization` HTTP header instead of the content body.
grant_type	Must have the value `refresh_token`
refresh_token	The `refresh_token` string that was included with the originally issued token.
redirect_uri	A reference to the same `redirect_uri` string used in step 1. This is used for security purposes to verify the request.

As per Step 3, we recommend you specify your client credentials using the Authorization header, rather than including these in the HTTP POST body.

Example request

An example token request (with the client_id and client_secret in the Authorization request header)

POST https://demo.arlo.co/oauth/connect/token HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic MTIzNDU2Nzg6QUJDREVGR0g=
Content-Type: application/x-www-form-urlencoded
Content-Length: 214

grant_type=refresh_token&code=refresh_token=2da9a39cd60848d88aa7a7c4dbf62086&redirect_uri=https://myapp.example.org/oauth/arlo/authcallback/

Token response structure

A successful refresh request will return a JSON object (a JWT) that you should parse and securely store, replacing any token you previously had stored.

{  
  "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE...ImEzck1VZ0",
  "access_token":"8ae774a676294f798d0cf4704e145937",
  "refresh_token":"04238b11a9774eb1b51e19699823934a",
  "expires_in":3600,
  "token_type":"Bearer"
}

The JWT structure fields are the same as those defined in Step 3.

Note that the JWT will include a new refresh_token value that you should use in future refresh requests instead of the token that was originally issued with the first request.

Validating an access token

To check if an access token is valid, make a GET request to the following endpoint:

/{platform_name}/oauth/connect/accesstokenvalidation

where {platform_name} is the name of the platform.

You must include the following parameters (which must be URI encoded):

Parameter	Description
token	The access token to check.

You shouldn't need to call this API frequently. Follow our token caching guidelines and wait for a HTTP 401 or 403 response for a general API request before using this API to check if the token is valid.

Example request

An example validation request:

GET https://demo.arlo.co/oauth/connect/accesstokenvalidation?token=649179135ca5df91b1f5ba6fc85b6df HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate

HTTP status codes

The HTTP status of the response will indicate if the token is valid.

Status	Description
200 OK	The token is valid.
400 Bad Request	The token is not valid.

Response

A successful refresh request will return a JSON object with token claim details. In general, the claims are implementation specific and you should avoid parsing them as they may change between requests.

The HTTP 200 OK response status is sufficient to indicate that a token is valid, and you do not need to examine the content of the response.

Revoking an access or refresh token

To revoke a previously issued access or refresh token, make a POST request to the following endpoint which follows the RFC 7009 specification:

/{platform_name}/oauth/connect/revocation

where {platform_name} is the name of the platform.

You must include the following parameters (which must be URI encoded):

Parameter	Description
client_id	The unique identifier you obtained when you registered your application with Arlo. We recommend you put this in the `Authorization` HTTP header instead of the content body.
client_secret	The secret you obtained when you registered your application with Arlo. We recommend you put this in the `Authorization` HTTP header instead of the content body.
token	A reference to the access or refresh token to revoke.
token_type_hint	A reference to type of token specified. Must be either `refresh_token` or `access_token`.

The invalidation takes place immediately, and the token cannot be used again after the revocation.

Example request

An example revoke request (with the client_id and client_secret in the Authorization request header)

POST https://demo.arlo.co/oauth/connect/revocation HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic MTIzNDU2Nzg6QUJDREVGR0g=
Content-Type: application/x-www-form-urlencoded
Content-Length: 102

token=4cfc8af8a1cd99ecdcf090dafea14632&token_type_hint=access_token

HTTP status codes

The HTTP status of the response will indicate the success of the operation.

Status	Description
200 OK	The request is valid, and the token has been revoked.
400 Bad Request	The request is not valid.

Response

The HTTP 200 OK response status is sufficient to indicate that the revocation request has been accepted, and you do not need to examine the content of the response.