OAuth API

Your application or website can interact with Gloebit user-accounts by using Gloebit’s API.

To interact with a user’s Gloebit account, the user must grant permission. Your application sends the user’s browser to Gloebit’s website where the user is presented with a permission dialog. If the user agrees, a token is sent back to your application. Your application includes the token with API requests to prove that the user has allowed access to their account.

The API allows various operations, such as querying the user’s balance or initiating transactions between the user and your application.

Either OAuth 1.0a or OAuth 2.0 is used for authentication. Any data delivered to or received from API requests will have a Content-Type of application/json. All requests go over https.

OAuth 1.0a

There are many client libraries for OAuth 1.0a.

The request-token url can be modified with an optional “user” query-arg. If provided, it should be the username of the account on the consumer side (the username as your application knows it). It will be recorded in the token and used for display purposes, only.

operation endpoint
Request Token https://www.gloebit.com/oauth/request-token
Authorize https://www.gloebit.com/oauth/authorize
Access Token https://www.gloebit.com/oauth/access-token

The application first gets a Request Token from Gloebit. This token isn’t associated with a particular user or domain. Next, the application sends the user to Gloebit’s authorization page. If the user agrees to grant access, the Request Token is authorized and a specific user and domain are associated with it. Next, the application exchanges the authorized Request Token for an Access Token. The Access Token is used during API requests.

OAuth 2.0

Gloebit supports three-legged OAuth 2.0.

The authorize url should be modified with some query args:

query argument value
client_id the consumer (application / 3rd party) key
response_type Gloebit only uses “code” response type.
redirect_uri Where to send the user after the permission dialog.
scope a space separated list of what permissions are being requested.
user an optional argument. If provided, it should be the username of the account on the consumer side. It will be recorded in the token and used for display purposes, only.

Once the user grants permission, they will be redirected back to the redirect_uri with a code query-arg.

operation endpoint
Access-Token https://www.gloebit.com/oauth2/access-token
Authorize https://www.gloebit.com/oauth2/authorize

Overview of OAuth 2.0 Flow:

The application sends the user to Gloebit’s authorization page. Once the user has agreed, a token id (the code query arguement) is included and the user is sent to the redirect_uri. The application then validates the token. The token is used as the value of the Authorization HTTP header during any API requests.

Sandbox

Gloebit provides a “sandbox” server. This server is just like the main server, except that interactions with payment providers are in test or sandbox mode. Generally, substitute sandbox.gloebit.com for www.gloebit.com in order to use the sandbox server. The sandbox server has its own accounts and balances – anything done on the sandbox server will need to be repeated on the main server, once testing is complete.

Notes about sandbox mode:

payment provider notes
Amazon FPS The CC number and billing address wont be real; this is expected.
Paypal An account must be set up ahead of time to test here.
Stripe see Stripe’s Testing page for usable credit card numbers.
Coinbase There’s not actually a sandbox mode here, but we can reimburse bitcoins without any cost.

Domain/Scope

When retrieving OAuth tokens, use these strings for the domain (for OAuth 1.0a) or scope (for OAuth 2.0). The value should be one string containing space separated parts.

domain name endpoints
id The authorization dialog will be Gloebit’s character creation/selection dialog rather than the access request dialog.
balance Allows use of the Balance endpoint.
transact Allows use of the Transact endpoint.
inventory Allows use of the Inventory endpoints.

Account Endpoints

These API endpoints require a valid access-token. The domain/scope of the access-token must be appropriate for whichever request is being made.

Identity

domain endpoint
id https://www.gloebit.com/id

When the domain/scope includes id, a character creation/selection dialog is used during the authorization step of the OAuth flow. The selected character will determine the values in the response to this request.

response

key value
id UUID for whichever character the user selected.
name Name of the selected character.
params dictionary of parameters associated with the selected character.

Balance

domain endpoint
balance https://www.gloebit.com/balance

Response

key value
success boolean
reason explanation of (lack of) success
balance user’s G$ balance

Transact

domain endpoint
transact https://www.gloebit.com/transact

Check validity of a merchant’s transaction request and then put it into the inbound queue.

The post body should be a json dictionary with these keys:

key value
version integer, 1
id string, transaction id, generated by client
request-created integer, seconds since 1970
asset-code string, optional
asset-quantity integer, optional
asset-enact-hold-url string, optional
asset-consume-hold-url string, optional
asset-cancel-hold-url string, optional
gloebit-balance-change number of G$ to charge the user, defaults to 0
product string, optional – name of product to grant user
product-quantity positive integer, many of product to grant user, defaults to 1
consumer-key string
merchant-user-id string, merchant’s local id for this user

For example, if the merchant has defined a product called “green-hat” which costs 40 gloebits, the posted json dictiony might look like:

    {"version": 1,
     "id": "ec8d8f47-2648-4378-8734-bba45852a60f",
     "request-created": 1399828892,
     "product": "green-hat",
     "gloebit-balance-change": 40,
     "consumer-key": "7f6bebb4-6ac9-4eb3-b7ad-ea847f2dc54d",
     "merchant-user-id": "whatever my game knows this user as."
    }

“version” should be 1. “id” should be a new uuid, generated by the merchant’s application. “request-created” should be similar to what the unix command date ‘+%s’ produces. “product” should be a product-name as defined in the Merchant Products page (or the sandbox version). “consumer-key” is the Key field from the Merchant Settings page. “merchant-user-id” should be the application specific name for the user, and is only used for logging and transaction history display.

The response will also be a json dictionary:

key value
id string, same as request
status string, one of “queued”, “queuing-failed”, “in-progress”
success boolean
reason string, human readable explaination of status

Inventory Endpoints

A user’s Inventory is a json dictionary with inventory-item-names as keys and inventory-items as values. Each inventory-item is also a json dictionary (called params, below). The contents of the inventory-item is up to the developer. A folder-id and type-id are also associated with each inventory item.

Inventory operations are per gloebit user, not per character. If per-character inventory is desired, use the character-id as a top-level folder.

New Inventory Item

domain endpoint
inventory https://www.gloebit.com/new-inventory-item

Create a new inventory item. Folder-id is optional and will default to a null (all zeros) uuid.

The request body should be a json dictionary:

key value
folder-id string
type-id string
params a dictionary

The response will be a json dictionary:

key value
success boolean
reason string
item-id string (uuid)

List Inventory Items

domain endpoint
inventory https://www.gloebit.com/get-inventory-item-ids
inventory https://www.gloebit.com/get-inventory-item-ids/*folder-id*

Retrieve a list of inventory item IDs for a user.

The response will be a json dictionary.

key value
success boolean
reason string
item-ids json array – Each element is a tuple of strings: (item-type-id, item-id, folder-id).

If folder-id isn’t specified, the entire inventory for the authorized user is returned. If a folder-id is given, only inventory items from that folder are returned. The root folder for a user is identified with a null UUID: “00000000-0000-0000-0000-000000000000”.

Get Inventory Item

domain endpoint
inventory https://www.gloebit.com/get-inventory-item/*item-id*

Retrieve details about a user’s inventory item.

The response will be a json dictionary:

The request body should be a json dictionary:

key value
success boolean
reason string
item details about inventory item (params)

Update Inventory Item Parameters

domain endpoint
inventory https://www.gloebit.com/update-inventory-item-params

Change details about a user’s inventory item. If the item isn’t found, a new one will be created.

The request body should be a json dictionary:

key value
id string
folder-id string
type-id string
params a dictionary

The response will be a json dictionary:

key value
success boolean
reason string

Delete Inventory Item

domain endpoint
inventory https://www.gloebit.com/delete-inventory-item/*item-id*

Delete a user’s inventory item.

The response will be a json dictionary:

key value
success boolean
reason string

Product Endpoints

Products are predefined inventory items. A merchant can define products by visiting the Merchant Products page (or the sandbox version).

Products must have a unique name (within a given merchant’s account). The price is indicated in gloebits. Per-user-limit limits how many of each product one user can own. See Transact for how to give a user more of a product.

Get User Products

domain endpoint
inventory https://www.gloebit.com/get-user-products/

Retrieve a list of products/entitlements owned by the user.

The response will be a json dictionary:

key value
success boolean
reason string
products json dictionary with product names as keys and counts as values.

Consume User Product

domain endpoint
inventory https://www.gloebit.com/consume-user-product/*product-name*/*count*/

Decrease by count the number of a product owned by the user.

The response will be a json dictionary:

key value
success boolean
reason string
count integer – how many of product-name user has after this operation.

Errors

Any access-token protected API call returns a json dictionary. One of the entries will be ‘success’ which will be True or False. If ‘success’ is False, there will be an entry called ‘reason’, which will be set to one of: