Skip to content

Endpoint

Account

Properties

name type description
username string A 64 length string that identifies a user
name string User display name
email string A valid email for authentication
password string A minimum of 8 string password with combination of character and symbol

Header

name description
Content-Type The content type of the request. Only accepted application/json
Authorization Authorization header. Use Bearer Token.

1. Register

To register a user to the server, send a POST request to the endpoint below:

POST /v1/account/register

Request

Header

name value
Content-Type application/json

Body 

{
    "username": "required",
    "name": "required",
    "email": "required",
    "password": "required",
}

Response

Header

name value
Content-Type application/json

Properties

name description
error_type a string for telling the error type

Succesful Response (200 OK)

{
    "status": "success",
    "message": "your account is successfully created. OTP has been sent to your email."
}

Error Response

1. 400 Bad Request
There are various 400 error type, below is the details regarding all possible bad request error type:

error_type description
missing_parameter There are a missing parameters in the request provided
header_value_mismatch using non-supported content-type header
username_exists username already taken
username_invalid username content is invalid
email_exists email already registered
password_weak invalid password
invalid_email provided an invalid email 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "description": "details_regarding_the_error"
}

2. Verify OTP

After a successful registration, an OTP will be sent to the email on the request. To verify newly registered user, user must verify their account by sending a POST request to the endpoint below:

POST /v1/account/otp/verify

Request

  • Header
name value
Content-Type application/json
  • Body 
    {
    "email": "your_id_here",
    "otp": "your_OTP_here",
}

Response

Successful Response (200 OK)

  • Header
name value
Content-Type application/json
  • Body 
    {
    "status": "success",
    "message": "your account has been activated successfully"
}

Error Response
1. 400 Bad Request
This error can be caused by several reasons. The list of all possible error is listed below:

error_type description
missing_parameters some body parameters is missing
header_value_mismatch Content-Type header isn't acceptable
invalid_otp OTP provided doesn't match with the server
otp_expired OTP provided has already expired, please re send a new otp 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "descriptipn": "details_regarding_your_error here",
}
  1. 404 Not Found
    This error caused by trying to verify otp from an active email or unregistered email. 
{
    "status": "error",
    "error_type": "email_not_found",
    "description": "email not exist or email already active"
}

3. Resend OTP

A user are able to re-send confirmation email with a new OTP. Re-send mail can be sent in a interval of 60 seconds. To re-send the mail, send a POST request to endpoint below:

POST /v1/account/otp/send

Request

  • Header
name value
Content-Type application/json
  • Body 
    {
    "email": "your_email_here"
}

Response

name value
Content-Type application/json

Successful Response (200 OK) 

{
    "status": "successfull",
    "message": "OTP has been re-send to your email.",
}

Error Response
1. 429 Too Many Requests
This error is caused by sending a re-send request too early. There are only one possible error type that is, otp_resend_interval_not_reached 

{
    "status": "error",
    "error_type": "otp_resend_interval_not_reached",
    "description": "Re send mail has already been sent"
}

4. Login

To log in user to the server and gain access to all service, sent a POST request to endpoint below:

POST /v1/account/login

Request

  • Header
name value
Content-Type application/json
  • Body 
    {
    "email": "your_email_here",
    "password": "your_password_here"
}

Response

Successful Response (200 OK) 

{
    "status": "success",
    "token": {
        "accesss_token": "your_token_here",
        "refresh_token": "your_refresh_token_here",
    }
}

Error Response
1. 400 Bad Request
This error can be caused by several reasons. The list of all possible error is listed below:

error_type description
missing_parameters some body parameters is missing
header_value_mismatch Content-Type header isn't acceptable 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "description": "details_regarding_your_error here",
}
  1. 401 Unauthenticated
    There are two error that can caused this status code, that is
error_type description
user_marked_inactive the user isn't registered successfully and currently marked as inactive
invalid_credentials email or password is invalid 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "descriptipn": "details_regarding_your_error here",
}

5. Patch User Info (NOT YET IMPLEMENTED)

Update user info partially, send a PATCH request to endpoint below:

PATCH /v1/account/{username}

Request

  • Header
name value
Content-Type application/json
Authorization Bearer your_token_here
  • Body 
    {
    "name": "your_new_name_here" (optional),
}

Response

  • Header
name value
Content-Type application/json

  • Successful Response (200 OK) 

    {
    "status": "success",
    "message": "Success updating user info"
}

  • Error Response
    1. 400 Bad Request
    This error can be caused by several reasons. The list of all possible error is listed below:

error_type description
header_value_mismatch Content-Type header isn't acceptable 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "descriptipn": "details_regarding_your_error here",
}
  1. 403 Forbidden
error_type description
Invalid_auth_header The header specified a wrong auth method other than Bearer Token
empty_auth_header Auth header is empty
invalid_token Token provided is invalid
token_expired Token has already expired 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "descriptipn": "details_regarding_your_error here",
}
  1. 404 Not Found Username not found

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED.

This endpoint is for storing user steamid into the database.

Endpoint

POST /v1/account/{username}/steam

Request

  • Header
name value
Content-Type application/json
  • Body 
    {
    "steamid": "steam id"
}

Response

Successful Response (200 OK)

{
    "status": "success",
    "message": "account is linked successfully"
}

Error Response
1. 400 Bad Request
This error can be caused by several reasons. The list of all possible error is listed below:

error_type description
missing_parameters some body parameters is missing
header_value_mismatch Content-Type header isn't acceptable 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "description": "details_regarding_your_error here",
}
  1. 404 Not Found
    This error is caused by username in the path parameter doesn't exist 
    {
    "status": "error",
    "error_type": "username_not_found",
    "description": "username not found",
}

This endpoint is for rollback steam linking

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED.

Endpoint

DELETE /v1/account/{username}/steam

Response

Successful Response (200 OK)

{
    "status": "success",
    "message": "account is linked successfully"
}

Error Response
1. 400 Bad Request
This error can be caused by several reasons. The list of all possible error is listed below:

error_type description
missing_parameters some body parameters is missing
header_value_mismatch Content-Type header isn't acceptable 
{
    "status": "error",
    "error_type": "your_error_type_here",
    "description": "details_regarding_your_error here",
}
  1. 404 Not Found
    This error is caused by username in the path parameter doesn't exist
{
    "status": "error",
    "error_type": "username_not_found",
    "description": "username not found",
}

8. Get Steam ID

This endpoint is for get the steam id of an account

Endpoint

GET /v1/account/{username}/steamid

Response

Successful Response (200 OK) 

{
    "status": "success",
    "steamid": "your steam id"
}

Error Response
1. 400 Bad Request
There are only one error response on this endpoint, and that is steam_not_linked. It was caused by trying to get steam id when the account hasn't been linked to a valid steam account. 

{
    "status": "fail",
    "error_type": "steam_not_linked",
    "description": "account hasn't been linked to steam yet"
}

9. Logout

This endpoint to logout your account from the service. After logout all of your token (access token and refresh token) will be revoked

Endpoint

POST /v1/account/logout

Request

  • Header
name value
Content-Type application/json
Authorization Bearer your_token_here
  • Body 
    {
    'username': 'fried_rice'
}

Auth

Properties

name description
username valid account username for token claims
email valid account email for token claims
roles the roles of the user that issued the token

Token Type

  1. Auth Token
    Give access to verified user to endpoint that can be accessed with their credentials. This token is set to expired 15 minutes after the token has been issued.
  2. Refresh Token
    Token for refresh auth token. This token will expired 1 day after the token has been issued.

Info

When auth token is refreshed, the refresh token also refreshed. So refresh token will expired after 1 day of inactivity.

1. Issue Token

To issue an access token for user, send a POST request to endpoint.

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED. 

POST /v1/auth/token

Request

  • Header
name value
Content-Type application/json
X-Client-Cert base64 encoded certificate

Info

Appending certificate onto the header is optional, the server accept client TLS Certificate if given.

  • Body 
    {
    "username": "issuer username",
    "email": "issuer email",
    "roles": "user role (user/admin)"
}

Response

  • Header
name value
Content-Type application/json

  • Successful Response (200 OK) 

    {
    "status": "success",
    "access_token": "token",
    "refresh_token": "refresh",
}

  • Failed Response 1. 400 Bad Request
    Below is several error that caused this error code:

error_type description
missing_parameter There are a missing parameters in the request provided
header_value_mismatch using non-supported content-type header
  1. 403 Unauthorized
    Only error for this code is access_denied. This happens when the client doesn't provide a valid certificate.

2. (PUBLIC) Refresh Token

To refresh auth token, send a POST request to this endpoint

POST /v1/auth/token/refresh

Request

  • Header
name value
Content-Type application/json
* Body 
{
    "access_token": "your_expired_token_here",
    "refresh_token": "your_valid_refresh_token_here",
}

Response

  • Successful Response (200 OK) 

    {
    "status": "success", 
    "access_token": "your_new_access_token",
    "refresh_token": "your_new_refresh_token".
}

  • Failed Response 1. 403 Unauthorized
    This status is returned because of the issued token doesn't meet required conditions. Here are the error that can arise from this error code:

error_type description
refresh_denied cannot refresh access token because the previous one still active
token_invalid access token invalid or refresh token invalid or your access token is revoked
token_expired refresh token is expired
claim_mismatch your access token and refresh token has different credentials

Info

Revoked access token cannot be refreshed.

  1. 400 Bad Request
    Below is several error that caused this error code:
error_type description
missing_parameter There are a missing parameters in the request provided
header_value_mismatch using non-supported content-type header

3. Verify Credentials

This endpoint is for verifying your credentials. Send a POST request to this endpoint.

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED. 

POST /v1/auth/verify

Request

  • Header
name value
Content-Type application/json
X-Client-Cert base64 encoded certificate

Info

Appending certificate onto the header is optional, the server accept client TLS Certificate if given.

Request

  • Body 
    {
    "token": "your_token_here",
    "endpoint": "the_endpoint_the_user_try_to_access"
}

Response

  1. 403 Unauthorized
    This status is returned because of the token doesn't meet required conditions. Here are the error that can arise from this error code:
error_type description
token_invalid either the access token or refresh token is invalid
token_expired refresh token is expired
access_denied you don't have access to the endpoint
  1. 400 Bad Request
    Below is several error that caused this error code:
error_type description
missing_parameter There are a missing parameters in the request provided
header_value_mismatch using non-supported content-type header

4. Revoked Access Token

To revoke an active token, send a POST request to this endpoint

POST /v1/auth/token/revoke

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED.

Info

Appending certificate onto the header is optional, the server accept client TLS Certificate if given.

Request

  • Header
name value
Content-Type application/json
X-Client-Cert base64 encoded certificate
  • Body
{
    "access_token": "access_token_that_need_to_be_revoked"
}

Response

  1. 403 Unauthorized
    This status is returned because of the token doesn't meet required conditions. Here are the error that can arise from this error code:
error_type description
access_denied you don't have access to the endpoint

Games

Properties

name type description
game_id int Game id assigned by steam
name string Game display name
display_picture string the url where the game display picture is stored
icon_url string the url where the game icon is stored

Storage Location Schema

{
    "protocol": "nas",
    "server": {
        "ip": "192.168.0.1",
        "port": "optional"
    },
    "path": "some/path/to/the/location"
}

Header

name description
Content-Type The content type of the request. Only accepted application/json

1. Sync Games to User Account

This is endpoint to sync user owned games in steam and add supported games to user games collections.

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED.

Endpoint

POST /v1/games/{username}/sync

Request

  • Header
name value
Content-Type application/json
X-Client-Cert base64 encoded certificate
  • Body
{
    "games": [
        {
            "name": "example game",
            "icon_url": "http://media.steampowered.com/steamcommunity/public/images/apps/{appid}/{hash}.jpg"
            "_id": "12312312321",
        }, 
        {
            ...
        }
    ]
}

2. Get User Games Collections

This endpoint is for getting user collections of games.

Endpoint

GET /v1/games/{username}/collections

Query Parameters

parameter description
cursor this parameter is used to get entry greater than this value. Default is 0
limit this parameter is used to specify how many values will be returned after the cursor. Default is 10. The maximum value is 100

Pagination

To get the first page, send request to this endpoint without specifying the offset or set offset to 0. Then to access the next page, use the offset value returned at the response.

Request

  • Header*
name value
Authorization Bearer Token

Response

  • Header
name value
Content-Type application/json
  • Body

Successful Response (200 OK) 

{
    "games": [
        {
            "game_id": "some_id_here",
            "name": "some_name_here",
            "game_icon": "http://path/to/icon.jpg",
            "display_picture": "http://path/to/display.jpg"
        }
    ],

    "offset": "12321"
}

Error Response
1. 403 Unauthorized
This status is returned because of the token doesn't meet required conditions. Here are the error that can arise from this error code:

error_type description
token_invalid access token is invalid
token_expired refresh token is expired
access_denied you don't have access to this route

3. Play Games

This endpoint is for creating a new session (VM) populated with requested games.

Endpoint

POST /v1/games/play

Request

  • Header*
name value
Authorization Bearer Token
Content-Type application/json
  • Body 
    {
    "game_id": "122131",
    "username": "username"
    "gpu": "(optional)"
}

Info

When you leave the GPU empty, a random gpu will be selected for the session

Response

Successful Response 

{
    "status": "success",
    "message": "session request has been successfully created",
    "session_id": "your_session_id"
}

Error Response
1. 403 Unauthorized
This status is returned because of the token doesn't meet required conditions. Here are the error that can arise from this error code:

error_type description
token_invalid access token is invalid
token_expired refresh token is expired
access_denied you don't have access to this route
  1. 400 Bad Request
    Below is several error that caused this error code:
error_type description
missing_parameter There are a missing parameters in the request provided
header_value_mismatch using non-supported content-type header
  1. 404 Not Found
    This is can either be invoked when game id is invalid or there is currently zero available GPU for the session.

Session

This is a service that handle as middleware between client and session manager.

1. Create New Session

Create new session request to session manager

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED.

Endpoint

POST /v1/session/create

Request

  • Header
name value
Content-Type application/json
X-Client-Cert base64 encoded certificate
  • Body 
    {
    "username": "username"
    "session_metadata": {
        "game_id": 14121,
        "game_location": {
            "protocol": "nas",
            "server": {
                "ip": "192.168.101.1",
            }
            "path": "/location/to/ganme"
        }
    }
}

Response

Successful Response (200 OK)

{
    "status": "success",
    "session_id": "uuid-v7-id"
}

2. Get Session Status

View the status of the request

Request Status

1. Provisioning
This is the step where the session service successfully create a VM creation request to session manager.

2.WaitingForConnection
This is the step where the VM requested has changed it's status to Running and waiting for the client to connect to the VM Virtual LAN. (via ZeroTier)

3. Running
This is the step where configuration has set up successfully and client can used the VM.

4. Failed
Some step has failed and the VM creation is cancelled.

Endpoint

GET /v1/session/{session_id}/status

Request

  • Header*
name value
Authorization Bearer Token
Content-Type application/json

Response

Successful Response (200 OK) 

{
    "status": "Provisioning"
    "network_id": "[This will be empty when status is provisioning]" 
}
Error Response
1. 403 Unauthorized
This status is returned because of the token doesn't meet required conditions or you are trying to access route without the correct permission. Here are the error that can arise from this error code:

error_type description
token_invalid access token is invalid
token_expired refresh token is expired
access_denied you don't have access to this route
  1. 404 Not Found This status returned when you are trying to get status of session_id that isn't exist.

3. Start Connection Establishment

Important

This endpoint only available for INTERNAL USE. The service will check the client certificate before proceeding the request. If the certificate NOT ISSUED by our CERTIFICATE MANAGER, the request will be DECLINED.

Endpoint

POST /v1/session/{session_id}/connection/start

Request

field_name type description
webhook string server address that will be called when data is ready
network_id string zerotier network id

Important

Make sure your endpoint has /pin route that accept JSON Content-Type for verifying user pin. The API will accept 200 as a valid response else it's considered as failure. The payload schema is the same as the Pair endpoint route below.

  • Body 
    {
    "webhook": {
        "host": "192.168.0.1",
        "port": "3000",
    },
    "network_id": "network_id",
}

Response

Successful Response (200 OK) 

{
    "status": "success",
    "message": "instance has been successfully attached to the session"
}

Error Response 1. 400 Bad Request
Below is several error that caused this error code:

error_type description
missing_parameter There are a missing parameters in the request provided
header_value_mismatch using non-supported content-type header

3. Pair

Start pairing sunshine with moonlight. When success, the status of the request will changed to Running. This endpoint need to be called from the client.

Endpoint

POST /v1/session/{session_id}/pair

Request

{
    "pin": "your_pin_here"
}

Successful Reponse (200 OK) 

{
    "status": "success".
    "message": "client has been paired successfully to the session instance"
}

Error Response 1. 400 Bad Request
Below is several error that caused this error code:

error_type description
missing_parameter There are a missing parameters in the request provided
header_value_mismatch using non-supported content-type header
invalid_pin pin provided is incorrect

4. Terminate Session

Terminate current session. This will not remove gpu from user session. Seperate call need to be made acquire the gpu back to the pool.

Endpoint

POST /v1/session/{session_id}/terminate

5. Deacquire GPU

Remove GPU from user session, and bring back to the pool

Endpoint

POST /v1/session/{session_id}/gpu/deacquire

6. Get GPU Status

Get all available gpu on the system

Endpoint

GET /v1/session/gpu

Query Parameters

parameter description
only_available Set this value to true to only list gpu that are available. Default is 0
limit this parameter is used to specify how many values will be returned after the cursor.