Authentication

Samsung Health Platform relies on OAuth2 to authenticate users as defined in RFC 6749. The client should obtain authorization from the resource owner. OAuth defines various grant types and Samsung Health Platform supports following grant types:

Authorization Code

The user is directed to a UI that allows him/her to sign in and authorize data permission. Upon user consent, the client is redirected to the application’s server with a an authorization code. The client must exchange that code for an access token that can be used with API calls.

Implicit

The user is directed to a UI that allows him/her to sign in and authorize data permission. Upon user consent, the client is redirected to the application’s server with URL fragment containing an access token. The access token can be used with API calls. This method is less secure and is suitable for applications that cannot protect the client secret enough, such as mobile applications.

Common information

Standard OAuth2 error response, https://tools.ietf.org/html/rfc6749#section-5.2, is used.

Common error response
Key Data Type Mandatory Description
error string Yes HTTP error code.
error description string Yes Human-readable text providing additional information.
state string Conditional The exact value received from the client, if a state parameter was present in the client request.
Common error response code
error error description
invalid_request Required parameter is missing or request is malformed
unauthorized Full authentication is required to access this resource
unauthorized_client The client is not authorized to request using this method
access_denied The resource owner or authorization server denied the request
unsupported_response_type Response type is not supported
invalid_scope The requested scope is invalid, unknown, or malformed
server_error The server encountered an expected condition to complete the request
temporarily_unavalialble The server is currently temporarily unable to handle the request

Authorization API

URI GET /auth/v1/authorize
Description Redirect the user to the authorization page.
Parameters client_id string Application ID.
response_type string code for authorization code grant flow.
token for implicit grant flow.
scope string A space-delimited list of the permissions with “.read” or “.write” suffix.
redirect_uri string This is the URL that will be called back and passed the result.
state string (OPTIONAL) A URL-safe value that is passed back when the follow is over.
language string (OPTIONAL) language for text displayed in the login screen (ISO-3166-2).
country string (OPTIONAL) country code for country-specific Samsung Account behavior in the login screen (ISO-639-1).
end_time long (OPTIONAL) desired end date for the service in milliseconds since the UNIX epoch (January 1, 1970, 00:00:00 UTC) If end time is specified.
  • Authorization page has service date information to be shown to user.
  • Token cannot be valid after the end time.
  • Token cannot be refreshed after the end time.
Success Response Body code string (Authorization code grant only) the authorization code by the server.
scope string (Implicit grant only) list of permissions issue to the client. When all permissions are selected by user, this value is not provided.
state string The exact value received from the client.
access_token string (Implicit grant only) access token that can be used with API calls.
expires_in long (Implicit grant only) the lifetime in seconds of the access token.
token_type string (Implicit grant only) always bearer.

Token API

URI POST /auth/v1/token
Description Exchange authorization code for an access token or retrieve new access token using refresh tokene.
Header Authorization Authorization header for the client credentials (e.g. “Basic “ + base64(client_id + “:” + client_secret)).
Parameters grant_type string authorization_code for Authorization Code Grant
refresh_token for token refresh.
code string (OPTIONAL) when requesting access token, the authorization code received from server.
refresh_token string (OPTIONAL) when refreshing access token, the refresh token issued to the client.
redirect_uri string This is the URL that will be called back and passed to the result. This URL should be identical to that of authorization API.
Success Response Body access_token string Access token that can be used with API calls.
expires_in long The lifetime in seconds of the access token.
refresh_token string Refresh token that can be used to refresh access token.
token_type string The type of the token issued, which is always bearer.
scope string List of permissions issue to the client.

Revocation API

URI POST /auth/clients/revoke
Description Revoke user access for the given client
Header Authorization Authorization header for credentials with user access token (e.g. “Bearer “ + access_token)
Parameters user_id string (OPTIONAL) User ID