Usage

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 Error Codes for details.

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 <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:

  1. Current time as integer POSIX timestamp (TIMESTAMP).
  2. HTTP method of request (METHOD).
  3. URL path of used endpoint (URL not including scheme, host name, or HTTP query parameters).
  4. If request has query parameters, param_name=value pairs sorted by parameter name, values must not be URL-encoded.
  5. 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

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 <session_token>.

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.

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.