.. usage.rst Copyright (c) 2016-2017 LMG. All rights reserved This software is the confidential and proprietary information of LMG ("Confidential Information"). You must not disclose such Confidential Information. Created by usischev on 22.04.17 Usage ----- .. contents:: :local: Requirements """""""""""" GoPoints API is accessed via HTTPS protocol, each method (endpoint) has corresponding HTTP method and URL path. When transferring data in request and response body, JSON is used with setting ``Content-Type: application/json`` header. GoPoints API is provided for registered client applications. Each API request has to provide the following: * **protocol and hostname** for HTTP requests. For sandbox environment API it is ``https://snbx-api.gopoints.net``. * **company_code** is the first component of URL path for all requests, e.g.: ``https://snbx-api.gopoints.net/000000/v1/auth/login`` Here ``000000`` is the ``company_code``, it will be the same for all requests client application sends. * **api_key** is assigned to each client application (see below). API Keys """""""" Each registered client application is assigned an API key. All requests made by a client application must have ``X-Api-Key`` header containing its API key. If this header is missing, ``auth.apikey.missing`` error is returned. If supplied API key is invalid, ``auth.apikey.invalid`` is returned. See :ref:`error-codes-label` for details. .. _crit-auth-label: .. rubric:: Critical change authentication When a client application calls an API endpoint making a critical change on behalf of a user with authorized session, such endpoints have optional ``password`` and ``otp`` request arguments to confirm user authentication. Client application API key may have critical change authentication requirement enabled or disabled. With enabled critical change authentication, for users with a password set, requests must supply valid password. For users without a password, a confirmation SMS OTP is sent and must be supplied in request. When critical change authentication data is missing in request, ``critical.auth.required`` error code is returned with ``critical_auth_method`` response field set to ``password`` or ``otp``. When client application receives ``critical.auth.required`` error code, it should ask user to provide password or SMS OTP and then call the same endpoint supplying ``password`` or ``otp`` request argument respectively. When invalid password or SMS OTP is supplied, ``auth.password.invalid`` or ``auth.otp.invalid`` error code is returned, respectively. Before ``auth.otp.invalid`` error code is returned, a new SMS OTP is sent to user. Client application should ask user to re-enter password or SMS OTP and call the same API endpoint again, supplying the new value in ``password`` or ``otp`` request argument. If API key does not require critical change authentication, ``password`` and ``otp`` request fields can be omitted or set to empty strings for such endpoints. API endpoints that provide initial user authentication and access recovery and do not require an authorized user session are not affected by critical change authentication settings. Request Signature """"""""""""""""" Specialized API methods (endpoints) require all incoming requests to be signed and have ``Authorization`` header with value ``Signature ``. Client application must use its secret key to create request signatures. As secret keys can contain any random bytes they are represented using URL-safe Base64 encoding (RFC 3548 Section 4). When creating signatures, secret key must be used in its original form (decoded from URL-safe Base64). The following request data is used for signatures: #. Current time as integer POSIX timestamp (``TIMESTAMP``). #. HTTP method of request (``METHOD``). #. URL path of used endpoint (``URL`` not including scheme, host name, or HTTP query parameters). #. If request has query parameters, ``param_name=value`` pairs sorted by parameter name, values must not be URL-encoded. #. If request has body (usually JSON for ``POST`` or ``PUT`` requests), body text exactly as sent. All these values are joined into a multi-line UTF-8 string with lines separated by newline symbol (``\n``). Then HMAC-SHA-256 of this string as hex digest (``HMAC_RESULT``) is generated using the secret key. Timestamp and HMAC result form the signature for HTTP header: ``Authorization: Signature TIMESTAMP;HMAC_RESULT`` **Example** Client application was assigned a secret key: ``SECRET_KEY_01234``. When issued, this key was represented using URL-safe Base64 encoding: ``U0VDUkVUX0tFWV8wMTIzNA==``. This client application is making a ``POST`` request with ``/000000/test/search?size=10&from=50`` URL (including query parameters) and JSON body ``{"text": "Quick brown fox", "simple": true}``. Current timestamp is ``1451638800``. Application forms the following multi-line UTF-8 string (lines separated with ``\n`` symbol, no trailing newline):: 1451638800 POST /000000/test/search from=50 size=10 {"text": "Quick brown fox", "simple": true} HMAC-SHA-256 hex digest of this string using ``SECRET_KEY_01234`` key is: ``f3aadb1d57b7c7b01d26e1f60ab14b09a5da5541e5fef624ac6661ed5198dd7c`` Resulting request signature HTTP header (all on one line): ``Authorization: Signature 1451638800;f3aadb1d57b7c7b01d26e1f60ab14b09a5da5541e5fef624ac6661ed5198dd7c`` User Access Permissions """"""""""""""""""""""" .. rubric:: Authorization Most generic level API methods (endpoints) require a valid user session. Upon successful authorization, API returns a ``session_token``. All further requests must have ``Authorization`` header with value ``Bearer ``. Each person and organization represented at the platform has a profile object. An authorized user acts on behalf of a person or organization, their permissions are determined by their profile. .. rubric:: Profiles and roles Each profile has a named role, for example, ``CLIENT``, ``USER``, ``PARTNER``, ``EMPLOYEE``, ``COMPANY``. Some API endpoints are allowed only for users with certain roles. Apart from role names, profile roles form a hierarchy. Each profile only has access to itself and other profiles with subordinate roles ("below" it in the hierarchy). For example, a ``PARTNER`` profile representing a partner bank can access ``CLIENT`` profiles of this bank but not profiles of another partner or its clients. Many objects like products or product entries are associated with some profiles. Access permissions to such objects are determined by access to profiles they belong to. API endpoints that check access permissions return ``auth.restricted`` error code if access to an object is not authorized.