Filter results by

Authentication

ARTIK cloud services rely on OAuth2 to authenticate users.

To learn about OAuth2, see the official getting started documentation, OAuth 2.0 Framework RFC, and RFC for PKCE.

Libraries are available for many programming languages and platforms. We recommend AppAuth (maintained by OpenID) for Android and iOS/OSX development.

The accompanying article Accounts describes how to manage the login experience and account settings for a user.

A user, application or device must first obtain an access token from ARTIK cloud services to make API calls. There are three types of tokens, defined in Access tokens.

An access token obtained from ARTIK cloud services is then passed to API calls, either as an HTTP Authorization header (preferred method), or as a URL parameter for WebSocket calls, which do not typically support HTTP headers.

OAuth2 offers several methods of obtaining access tokens, and we support the following:

  • Authorization Code: The user is directed by the application to a UI that allows him/her to sign in or create an account. A successful signin or signup results in a redirection to your application's server with an authorization code. Your application must then exchange that code on the server side for an access token that can directly be used with our API calls. This method is used when it is possible to keep the application secret secure, such as on the server side of a web application.
  • Authorization Code with PKCE: The user is directed to a UI that allows him/her to sign in or create an account. The application sends, with this redirection, an encrypted client verifier code that will be used later. A successful signin or signup results in a redirection to your application using the redirect URI. The redirection contains an authorization code. Your application must then exchange the authorization code on the server side for an access token that can directly be used with our API calls. Your application must send with the authorization code the client verifier code that will be verified on the server before the token corresponding to the authorization code is issued. During this flow, the application must not send the application secret, as this flow is suitable for applications that cannot sufficiently protect the application secret. This method uses Proof Key for Code Exchange (PKCE) to improve the security of the Implicit and Authorization Code methods, and is recommended for installed applications (e.g., mobile or desktop applications).
  • Implicit: The user is directed to a UI that allows him/her to sign in or create an account. A successful signin or signup results in a redirection to your application's server with a URL fragment directly containing an access token. The access token can then directly be used in our API calls. This method is less secure, and is suitable for applications that cannot sufficently protect the application secret and cannot store a client code verifier (e.g., client-side JavaScript applications).
  • Limited Input: The application sends an initial request to ARTIK cloud services to get a "user code" that is displayed to the user. The application should prompt the user to sign into ARTIK cloud services and enter the code at the verification URL specified in the response to the initial request. The application meanwhile polls ARTIK cloud services on whether the user has provided the code. Once the code is entered, ARTIK cloud services reply to the application call with a user token. This OAuth2 flow is for applications running on a platform with no or limited input (TV, watch, etc). The platform needs only to be connected and able to display a message to the user.
  • Client Credentials: This allows applications to get access tokens so they can run API calls as an application rather than as an authenticated user. There is no login or user interface involved. The access token can then directly be used in our API calls that accept this kind of token. This method is suitable for server-side code, as it requires the application secret to be passed. Before accessing user data in this flow, the user must have granted your application permissions on his data during either an Authorization Code or Implicit flow.

For examples of how to build OAuth2 flows in your applications, see How to choose an OAuth2 method.

Selecting authentication methods

Limit the attack surface of your application by selecting only the necessary authentication method(s).

Multiple authentication methods can be enabled for your application in the "App Info" section of the Developer Dashboard.

If you select two or more authentication methods, ARTIK cloud services will attempt to issue a token for each method. This requires that ARTIK cloud services relax the necessary security constraints. Because your application will be less secure when using multiple authentication methods, we recommend using only one authentication method whenever possible.

  • If you use Client Credentials with any other methods: If your client secret is compromised, an attacker will be able to access all user data with only your client ID (not considered secret) and client secret.

Obtain a token

Endpoint

1
https://accounts.artik.cloud

The /signin endpoint will no longer be supported as of April 1, 2018. To achieve the same result, include prompt=login with /authorize.

The /signout endpoint will no longer be supported as of April 1, 2018. To achieve the same result, use the method outlined in Revoke a token.

Authorization Code method

The Authorization Code method is done in multiple legs. First, your application must redirect the user to our accounts server by calling the /authorize endpoint.

GET /authorize

If the user is already connected (using a session cookie), the login form is bypassed and the user is redirected to the OAuth2 flow.

Passing prompt=login causes ARTIK cloud services to display the login form even if the user is connected.

Example authorization request

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

Authorization request parameters

Parameter Description
client_id Your application ID.
response_type The response expected. Must be code in this case, as we are requesting an authorization code.
prompt (Optional) Displays a login form to the user. Must be login.
redirect_uri (Optional) The redirect URI you supplied when requesting the application ID. This is the URL that will be called back and passed the authorization code.
state (Optional) A value (must be URL-safe) that is passed back to you when the flow is over. This is useful to keep a state and can be whatever you wish.
account_type (Optional) Specify identity provider for login. Can be ARTIKCLOUD, SAMSUNG, GOOGLE or NAVER. If not specified, UI displays all 4 options.
test_css_blank (Optional) Causes ARTIK cloud services form to be displayed with an empty blank.css (ARTIKCLOUD account only).

The user is sent to the account identity provider specified by account_type, where s/he may sign in or create a new account. If the login is successful, the user will be asked to grant specific permissions on his/her data.

When the user clicks "Grant", s/he will be redirected to your server (at the redirect_uri) with an authorization code.

Example

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

The code can be exchanged for an access token within 60 seconds before expiring. For security, this access token request should be made server-side.

client_id and client_secret should be included in an HTTP Authorization header. Refer to Sending client_id and client_secret for details.

Example access token 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=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https://myapp.com/callback&state=abcdefgh

Access token request parameters

Parameter Description
grant_type The type of token being requested. In this case, we are requesting an Authorization Code type of access token.
redirect_uri (Optional) The redirect URI you supplied to us for your application.
code The authorization code returned by the authorize call.

Example response

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

Response parameters

Parameter Description
access_token Access token that can be used with API calls.
token_type Always bearer for now.
expires_in In seconds, indicates how long the access token will expire.
refresh_token Refresh token used to obtain a new access token.

Authorization Code with PKCE method

This method is fully described in RFC 7636.

The Authorization Code with PKCE method is done in multiple legs. First, your application must redirect the user to our accounts server by calling the /authorize endpoint.

GET /authorize

If the user is already connected (using a session cookie), the login form is bypassed and the user is redirected to the OAuth2 flow. Passing prompt=login causes ARTIK cloud services to display the login form even if the user is connected.

Example authorization request

1
https://accounts.artik.cloud/authorize?prompt=login&client_id=9628eef2a00d43d89b757b8d34373588&response_type=code&code_challenge=f1a2&code_challenge_method=S256&redirect_uri=com.myapp.example://callback&state=abcdefgh

Authorization request parameters

Parameter Description
client_id Your application ID.
response_type The response expected. Must be code in this case, as we are requesting an authorization code.
prompt (Optional) Displays a login form to the user. Must be login.
code_challenge Challenge derived from code_verifier (using code_challenge_method). Used to verify the authorization request and the access token request originated from the same client.
code_challenge_method Method used to compute the code_challenge from code_verifier. Must be S256.
redirect_uri (Optional) The redirect URI you supplied when requesting the application ID. This is the URL that will be called back and passed the authorization code.
state (Optional) A value (must be URL-safe) that is passed back to you when the flow is over. This is useful to keep a state and can be whatever you wish.
account_type (Optional) Specify identity provider for login. Can be ARTIKCLOUD, SAMSUNG, GOOGLE or NAVER. If not specified, UI displays all 4 options.
test_css_blank (Optional) Causes ARTIK cloud services form to be displayed with an empty blank.css (ARTIKCLOUD account only).

The application generates a client code verifier. A client code verifier should be a high-entropy cryptographic random STRING using the characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" with 43 to 128 characters (for example, a UUID is a good code verifier). This code verifier is then encrypted using the code_challenge_method to generate a client code challenge, code_challenge.

The user is sent to the account identity provider specified by account_type, where s/he may sign in or create a new account. This redirection must include code_challenge. If the login is successful, the user will be asked to grant specific permissions on his/her data.

When the user clicks "Grant", s/he will be redirected to your server (at the redirect_uri) with an authorization code.

Example

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

The authorization code can be exchanged for an access token within 60 seconds before expiring.

All request parameters should be passed in the POST body including client_id and code_verifier (the client code verifier used to generate code_challenge sent in the corresponding authorization request).

Example access token request

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

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=com.myapp.example://callback&state=abcdefgh&code_verifier=1234&client_id=9628eef2a00d43d89b757b8d34373588

Access token request parameters

Parameter Description
client_id Your application ID.
code_verifier The code verifier. Used to verify the authorization request and the access token request originated from the same client.
grant_type The type of token being requested. In this case, we are requesting an Authorization Code type of access token.
redirect_uri (Optional) The redirect URI you supplied to us for your application.
code The authorization code returned by the authorize call.

Example response

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

Response parameters

Parameter Description
access_token Access token that can be used with API calls.
token_type Always bearer for now.
expires_in In seconds, indicates how long the access token will expire.
refresh_token Refresh token used to obtain a new access token.

Implicit method

The Implicit method is useful in situations where client_secret cannot be kept safe with the application—e.g. in mobile and desktop apps, where the application code can easily be decompiled and reverse-engineered.

This method is less secure than Authorization Code, because it does not use client_secret to obtain the code. However, it is more secure for the user than having the application directly request the user's name and password.

First, your application must redirect the user to our accounts server by calling the /authorize endpoint.

GET /authorize

If the user is already connected (using a session cookie), the login form is bypassed and the user is redirected to the OAuth2 flow. Passing prompt=login causes ARTIK cloud services to display the login form even if the user is connected.

Example request

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

Request parameters

Parameter Description
client_id Your application ID.
response_type The response expected. Must be token in this case, as we are requesting an access token.
prompt (Optional) Displays a login form to the user. Must be login.
redirect_uri (Optional) The redirect URI you supplied to us for your application. This is the URL that will be in the redirection response.
state (Optional) A value (must be URL-safe) that is passed back to you when the flow is over. This is useful to keep a state and can be whatever you wish.
account_type (Optional) Specify identity provider for login. Can be ARTIKCLOUD, SAMSUNG, GOOGLE or NAVER. If not specified, UI displays all 4 options.
test_css_blank (Optional) Causes ARTIK cloud services form to be displayed with an empty blank.css (ARTIKCLOUD account only).

The user is sent to ARTIK Cloud Accounts, where s/he may sign in or create a new account. If the login is successful, the user will be asked to grant specific permissions on his/her data.

When the user clicks "Grant", your application will receive a 302 (redirection) response in which the access token can be parsed from the URL fragment.

Example response

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

Response parameters

Parameter Description
access_token Access token that can be used with API calls.
token_type Always bearer for now.
expires_in In seconds, indicates in how long the access token will expire.
refresh_token Refresh token used to obtain a new access token.

Limited Input method

Applications running on a platform with no or limited input, such as a TV or watch, can use the Limited Input method. The platform needs only to be connected and able to display a message to the user.

This method is fully described in OAuth 2.0 Device Flow RFC.

First, your application sends a request to ARTIK cloud services to get a user code.

POST /device/code

Example user code request

1
2
3
4
5
POST /device/code HTTP/1.1
Host: accounts.artik.cloud
Content-Type: application/x-www-form-urlencoded

client_id=9628eef2a00d43d89b757b8d34373588

User code request parameters

Parameter Description
client_id Your application ID.

Example response

1
2
3
4
5
6
7
{
  "device_code": "4432df18-8ba4-4c14-816b-74e78a007eb2",
  "user_code": "QUZD-PDAE",
  "verification_url": "https://artik.cloud/go",
  "expires_in": 1800,
  "interval": 5
}

Response parameters

Parameter Description
device_code A value that uniquely identifies the device running the application.
user_code A case-sensitive value that identifies an authorization request. The device will instruct the user to enter this code at verification_url.
verification_url The ARTIK cloud services URL where the user enters user_code and authorizes the device.
expires_in Time, in seconds, remaining for the user to enter user_code.
interval Time, in seconds, the device running the application should wait between polling requests.

Once it has retrieved the user code, your application should display the code and verification URL in a response to the user on the limited input device.

On a secondary device, such as a desktop computer or mobile phone, prompt the user to load the verification URL in a browser and enter the code. If the user is not logged into ARTIK cloud services, they will first be prompted to login or sign up.

The user will then see the following page on their secondary device:

OAuth2 Limited Input verification URL

Meanwhile, your application checks that the user has provided the code by polling ARTIK cloud services with the polling frequency specified in interval. The request parameters should be passed in the POST body.

Example access token request

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

client_id=9628eef2a00d43d89b757b8d34373588&grant_type=device_code&code=QUZD-PDAE

Access token request parameters

Parameter Description
client_id Your application ID.
code device_code returned by the previous call.
grant_type The type of token being requested. Must be either urn:ietf:params:oauth:grant-type:device_code or device_code.

If the user code has not been entered, ARTIK cloud services return an error response such as the following (more possible error codes are listed here).

Example response

1
2
3
  "error": "authorization_pending",
  "error_description": "Waiting for user code"
}

Once the user code has been entered, ARTIK cloud services will return a user token.

Example response

1
2
3
4
5
6
{
  "access_token": "4432df18-8ba4-4c14-816b-74e78a007eb2",
  "token_type": "bearer"
  "expires_in": 2862,
  "refresh_token": "6ccadf10-1584-4241-9529-de231a21918d",
}

Response parameters

Parameter Description
access_token Access token that can be used with API calls.
token_type Always bearer for now.
expires_in In seconds, indicates in how long the access token will expire.
refresh_token Refresh token used to obtain a new access token.

Client Credentials method

This type of access token allows an application to authenticate itself in situations where no user is directly involved. However, before the application can use this method to access a user's data, it should have asked the user to grant such access via UI, using the Authorization Code, Authorization Code with PKCE, Limited Input, or Implicit method.

This is an HTTP POST call that must be done server-side because it requires passing client_secret.

client_id and client_secret should be included in an HTTP Authorization header. Refer to Sending client_id and client_secret for details.

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

Request parameters

Parameter Description
grant_type The type of token being requested. In this case, we are requesting a Client Credentials type of access token.

Example response

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

Response parameters

Parameter Description
access_token Access token that can be used with API calls.
token_type Always bearer for now.
expires_in In seconds, indicates in how long the access token will expire.

Refresh a token

If an application obtains an access token using the Authorization Code, Authorization Code with PKCE, or Limited Input methods, it can refresh the token up to 14 days after the token has expired.

After 14 days, the original access token cannot be refreshed anymore and the application must get a new access token.

Authorization Code refresh

The application makes a POST call at the server side using a previously issued refresh_token.

client_id and client_secret should be included in an HTTP Authorization header. Refer to Sending client ID and client secret for details.

Request parameters

Parameter Description
grant_type Must be set to value refresh_token.
refresh_token Refresh token used to obtain a new access token.

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=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Example response

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "the_scope"
}

PKCE and Limited Input refresh

The following applies to the Authorization Code with PKCE and Limited Input methods.

The application makes a POST call at the server side using a previously issued refresh_token.

The below request parameters, including client_id, should be passed in the POST body.

Request parameters

Parameter Description
client_id Your application ID.
grant_type Must be set to value refresh_token.
refresh_token Refresh token used to obtain a new access token.

Example request

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

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=9628eef2a00d43d89b757b8d34373588

Example response

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "the_scope"
}

Sending client_id and client_secret

Sending client_id and client_secret is necessary when:

HTTP Basic authentication is the recommended way. You pass an Authorization header with Base64-encoded client_id and client_secret. Specifically, encode the following string:

1
client_id:client_secret

Put the above encoded string into the header. Below is an example Authorization header.

Example

1
Authorization: Basic cdddZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

Alternatively, the credentials (client_id and client_secret) can be included in the request body (not the request URI). This should only be used when HTTP Basic authentication is not possible.

Request parameters

Parameter Description
client_id Your application ID.
client_secret Your application secret.

In the following example, an HTTP request to refresh an access token includes client_id and client_secret in the request body, instead of in the Authorization header. Please note that this is not a recommended method of sending client_id and client_secret. Use HTTP Basic authentication whenever possible.

Example

1
2
3
4
5
6
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdddXXdqt3&client_secret=7Fggfpss0ZBr1KXXtDRbnfVdmIw

Validate a token

You can validate a token using this endpoint. This call will return the IDs and expiration time associated with the token. If the token has expired or is invalid, a 401 status code is returned.

GET /tokenInfo

Example

1
https://accounts.artik.cloud/tokenInfo?token=2YotnFZFEjr1zCsicMWpAA

Request parameters

Parameter Description
token Access token.

Example response

1
2
3
4
5
6
7
8
{
  "data": {
    "device_id": null,
    "user_id": "db2e64c653b94f519dbca8f157f73b79",
    "client_id": "9628eef2a00d43d89b757b8d34373588",
    "expires_in": 1000000
  }
}

Response parameters

Parameter Description
device_id Device ID associated with the device token. Null if token is a user/application token.
user_id User ID associated with the user token. Null if token is a device token.
client_id Application ID associated with the application token.
expires_in Time the token expires (in seconds).

Revoke a token

The /revokeAccessToken endpoint will no longer be supported as of April 1, 2018. The new endpoint is described below.

To completely invalidate a user session, you must revoke its assigned tokens.

If you wish to avoid having the user automatically reconnected on your next call to /authorize, include prompt=login with the call. See Authorization Code method for an example.

POST /revokeToken

Example

1
https://accounts.artik.cloud/revokeToken?token=0ea24090297b4108ae1338c39f25c118  

Request parameters

Parameter Description
token User token to invalidate.

Example response

1
2
3
4
5
{
  "data" : {
    "message" : "Token successfully revoked"
  }
}

Use an access token

Pass the token as an HTTP header

This is the preferred way of authenticating your call. Pass the Authorization header as follows on your HTTP call:

1
Authorization: bearer <access token>

Example

1
Authorization: bearer 1c20060d9b9f4ad09ee16919a45c71b7

Pass the token as a URL parameter

Only use this on WebSocket calls. (Learn more about implementing WebSockets in ARTIK cloud services for live-streaming data.)

Pass the Authorization header as a URL parameter:

1
?Authorization=bearer+<access token>

Example

1
wss://api.artik.cloud/v1.1/websocket?Authorization=bearer+1c20060d9b9f4ad09ee16919a45c71b7

Authentication errors

/authorize errors

For authorization code grants, the error code is included as an "error" query string parameter. For implicit grants, the error code is included as an "error" fragment parameter.

Http Status Error message Condition
400 Invalid parameter: redirect_uri The provided redirect_uri does not match the registered redirect_uri for the client application.
302 server_error Unexpected server error Sent to "redirect_uri", includes the state param.
500 There was a server error without a valid redirect_uri to resend it. An unexpected server error and invalid redirect_uri was provided.
302 invalid_request The request is missing a required parameter (other than redirect_uri), includes an unsupported parameter value, includes a parameter more than once or is otherwise malformed. Sent to "redirect_uri", includes the state param.
302 unauthorized_client The client is not authorized to request an authorization code using this method. Sent to "redirect_uri", includes the state param.
302 access_denied The user or the authorization server denied the request. Sent to "redirect_uri", includes the state param.

/token errors

The error is returned as a JSON object in a response like this:

1
2
3
4
5
6
7
8
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
   "error":"invalid_request"
}
Http Status Error message Condition
400 server_error Unexpected server error.
400 invalid_request The request is missing a required parameter (other than redirect_uri), includes an unsupported parameter value, includes a parameter more than once, or is otherwise malformed.
400 unauthorized_client The client is not authorized to request an authorization code using this method.
400 authorization_pending Waiting for user code.
400 slow_down Polling too frequently.
400 expired_token Device or user code expired.
302 unsupported_grant_type The authorization grant type is not supported by the authorization server.