Filter results by

OAuth2 flow examples

OAuth 2.0 is a protocol that allows external applications to request access to private data in a user’s ARTIK Cloud account without getting their passwords.

To learn about obtaining and refreshing access tokens, and the differences between the various authorization flows, first see Authentication. In this article, we give some examples of how third-party apps can build an OAuth 2.0 flow to interact with ARTIK Cloud.

Web applications

A real-world web application contains front-end components and back-end servers.

To improve security, your web application should initially use the Authorization Code method to have a user grant the app access to her data on ARTIK Cloud.

Later, your app could use the Client Credentials method on the back end to get a token to access the data without requiring further involvement from the user.

Obtain an access token by interacting with users

The Authorization Code method has two steps. First, the front end sends an HTTP request to get an authorization code. Then, the back end sends an HTTP request with client credentials and the obtained code to get an access token.

Obtain an authorization code

Your web application should present a UI for a user to log into ARTIK Cloud. Once the login button is clicked, the app then makes the HTTP call to request an authorization code from ARTIK Cloud. Below is an example of an HTTP GET request call:

1
https://accounts.artik.cloud/authorize?client_id=9628eef2a00d43d89b757b8d34373588&response_type=code&redirect_uri=https://myapp.com/callback&state=abcdefgh

The user will be presented an ARTIK Cloud Accounts screen, where she may sign in or create a new account. If login is successful, the user will be asked to grant specific permissions on her data.

When the user clicks "Grant", the server (at the redirect_uri) will receive an HTTP request with an authorization code as follows:

1
https://myapp.com/callback?code=0ee7fcd0abed470182b02cd649ec1c98&state=abcdefgh

Obtain an access token

Now your back-end server exchanges the authorization code obtained above for an access token within 60 seconds before expiring.

Since the client credentials will be used in this step, it is recommended that the back-end server sends the request. The credentials (client_id and client_secret) should be encoded in an HTTP Authorization header. Consult Sending client ID and client secret for details on how to include them in an HTTP request.

Below are examples of the HTTP request sent by your back-end server, and the response:

Example request

1
2
3
4
5
6
7
POST /token HTTP/1.1
Host: accounts.artik.cloud

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https://myapp.com/callback&state=abcdefgh

Example response

1
2
3
4
5
6
{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

Now your web application can use the token to make API calls to ARTIK Cloud, to access the corresponding user's data, until the token expires or the permissions are revoked.

You can continue to use Authorization Code flow to get the user's access token. Future interactions with your web application's UI only require the user to login, and does not require that she grant permission again, unless she revokes or changes the permissions.

However, it is preferable to have the web app perform API calls on behalf of a user without prompting another login. We describe how in the next section.

Obtain an access token without further user interaction

Once a user has granted your web app permission to access her data, the back-end server of the app can request an access token without further interaction from the user. This can be done two ways:

  • Refreshing a token.
  • Using the Client Credentials method.

In each method, we recommend that HTTP calls be performed by the back-end server because it requires passing the credentials (client_id and client_secret). The credentials are encoded in an HTTP Authorization header. Consult Sending client ID and client secret for details on how to include them in a HTTP request.

The token obtained by refreshing a token can access data of a specific user. The token obtained using the Client Credentials method can access data of all users that have granted permissions to the application.

Refresh a token

The back-end server can obtain a new access token by exchanging the refresh_token previously issued during the flow of the Authorization Code method. The new token allows access to the data of a specific user. Please see Refresh a token for more details.

Use Client Credentials method

As an alternative to refreshing tokens, the back-end server can use the Client Credentials method to get new tokens without prompting users again.

Below are examples of the HTTP request sent by your back-end server, and the response:

Example request

1
2
3
4
5
6
POST /token HTTP/1.1
Host: accounts.artik.cloud
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Example response

1
2
3
4
5
{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600
}

Standalone mobile applications

A mobile application that does not work with back-end servers (standalone mobile application) is less secure and cannot protect the client secret. Therefore, it is recommended that you use the Implicit method in a standalone mobile app.

The Implicit method is straightforward to use. It takes one step for a mobile app to get the access token. Please consult the Authentication for more details on this flow. The following is an example of the HTTP GET request sent by the mobile app:

Example request

1
https://accounts.artik.cloud/authorize?client_id=9628eef2a00d43d89b757b8d34373588&response_type=token&redirect_uri=https://myapp.com/callback&state=abcdefgh

After an user successfully logins and grants specific permissions on her data, the mobile app will receive a redirection response as the following:

Example response

1
2
HTTP/1.1 302 Found
Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&state=xyz&token_type=bearer&expires_in=7200

Instead of redirecting, the mobile app extracts the access token from the above response. Then it uses the token to make API calls to ARTIK Cloud until the token is revoked or expires.

Please consult Your first Android app for specific examples of using the Implicit method.

The mobile app can refresh the token if the token expires. Please see Refresh a token for more details.

Mobile applications with back-end servers

If your mobile application can work with your back-end servers, your app is likely more secure. The client secret can be stored in the back-end server. You use one of the following options to do the initial authentication and permission grant, depending on your preference:

After a user grants permissions to your mobile app during one of the above authentication workflows, the back-end server of the app can perform API calls without prompting the user to login again. This is done by refreshing tokens or using the Client Credentials method, just like in the above web application.