‘endpoint_sessions’

/api/v1/endpoints/{endpoint_id:[0-9a-fA-F]{32}}/sessions

/api/v1/endpoints/{endpoint_id:[0-9a-fA-F]{32}}/sessions/{endpoint_session_id:[a-zA-Z0-9]{32}}

Endpoint session management. Does not require login/endpoint session. Instead, it requires endpoint secret.

Session lifetime (TTL): expire on inactivity 60 min, max lifetime 10080 min. It may change without notice. Please handle 434/433 HTTP codes to re-open session on-the fly and re-send request.

POST

Create the session from endpoint ‘123’ and returns it’s ID:

POST /api/v1/endpoints/123/sessions
{
    'salt': 'client-generated salt',
    'endpoint_secret_hash': 'endpoint secret hashed by SHA-256 with salt',
    'session_data': {'any': { 'data': ['you', 'want to store', 'in session'] } }
}
returns
{
    'endpoint_session_id': 'nmk567'
}

Client machine knows in advance endpoint_secret and id. It sends it to server, in hashed+salted form. Server validates and returns endpoint_session_id or HTTP error.

endpoint_secret_hash calculation in python:

def get_endpoint_secret_hash(endpoint, salt):
    # Calculates endpoint secret hash as SHA256(endpoint.secret, SHA256(endpoint.id_hex + salt))
    # salt is random string of length >= 1

    salted_endpoint_id = (endpoint.id_hex + salt).encode('utf-8')
    endpoint_id_hash = sha256(salted_endpoint_id).hexdigest()
    salted_enpoint_secret = (endpoint.secret + endpoint_id_hash).encode('utf-8')

    return sha256(salted_enpoint_secret).hexdigest()

GET

Read information about endpoint session:

GET /api/v1/endpoints/123/sessions/nmk567?salt=xxx&endpoint_secret_hash=yyy
returns
{
    'sid': 'ZLsXfOCPHgTQyrHovcEhAXA72KD8dlf8',
    'endpoint_id': '1aad375622de11e498e9000c294fde0e',
    'session_data': {'json': 'is cool!'}
}

DELETE

Destroys the endpoint session ‘nmk456’. You must know endpoint secret:

DELETE /api/v1/endpoints/123/sessions/nmk567?salt=xxx&endpoint_secret_hash=yyy