Welcome to the developer page providing all the information you need to integrate Gloebit services into your application. It combines reference information about the services and endpoint specifications for the services. It is meant to be read from the beginning onward. However, given the page's size, feel free to use the References and Endpoints menus to jump around.

Gloebit's Services

Gloebit offers four backend services: Identity, Character, Inventory, and Digital Currency. You can incorporate any of them into your design, or any combination, or all of them. Each can work independently or with other services (for example, character-based inventories).

All backend services are dependent upon the Gloebit Authorization service. Your application must first use the authorization service to get your user's approval for account access. Via this service, Gloebit will authorize the user, ask permission for your application's access, and provide your application an access token for the user's account. Your application then uses the token with the backend services.

Endpoints

All of the Gloebit services are web services, meaning their functionality is accessed via HTTP requests to web resources. This page uses the term "endpoint" to refer to a web resource, including its URL, its HTTP request format, and the functionality it provides. The Endpoints menu lists all of the web resources available in each of the services.

Your application must use Gloebit's Authorization service before using any of the other Gloebit services. All other services' endpoints require an access token, and you use the Authorization service to acquire access tokens. Gloebit supports OAuth 2.0 (OAuth2) methods for delivering access tokens to your application. During the OAuth2 flow, we will prompt your user to log into the Gloebit system and grant your application access to the user's resources (identity, characters, inventory, etc.) requested by your application.

An access token is a credential your application provides when accessing a Gloebit user's resources. Your application acquires an access token via the Authorization service and then includes it in requests to Gloebit's backend services. During the authorization process, Gloebit puts the following constraints on the access token:

• The access token is tied to the application requesting it, exclusively.
• It is valid only for the resources of the authorizing Gloebit user.
• It is valid until the user revokes the application's access.
• It grants access only to the resources in the token's scope.

User

The "user" associated with an access token is a Gloebit account. These users correspond to your application's users only if your application uses Gloebit IDs (from the Identity service) to identify or associate with its users. Otherwise, you should be aware that a user in your application could log into more than one Gloebit account or multiple users in your application could share a single Gloebit account (or many to many).

Scope

An access token's scope is a set of Gloebit-defined scopes that cover the user's resources available to applications. Your application will indicate the requested scope (set of Gloebit scopes) when initiating the Authorization service. Gloebit will inform the user of the requested scope during approval and then, after the user approves, return an access token with that scope. Here are the Gloebit resources and the Gloebit scopes for them:

For example, if your application wants to access a user's identity and balance and let the user purchase products in your application, you would request an access token with identity, balance, and transact in its scope. (Specifically, the requested scope is a space-separated string specifying them: "identity balance transact".)

Revocation

Currently, Gloebit does not explicitly expire access tokens. They can effectively expire due to storage constraints or other structural causes. Additionally, users can revoke an application's access via their Gloebit dashboard and approved-applications pages.

If a token expires or is revoked, Gloebit will reject any request your application makes with the token. When a request is rejected, your application should check the included failure reason and determine if it needs to return to the authorization process to acquire a new token.

Security

Keeping access tokens secure is paramount. They grant access to your users' Gloebit accounts and information your application stores for your users. Your application's method for storing access tokens must prevent their being exposed to users or third parties.

To get approvals from your users to let your application access their Gloebit accounts, we use the OAuth 2.0 (OAuth2) framework. OAuth2 supports securely authorizing your users and accessing their "resources". For a nice, succinct primer on OAuth2, visit Aaron Parecki's OAuth 2 Simplified page. For OAuth2 details, visit the OAuth 2.0 specification page.

Gloebit's OAuth2 implementation supports both confidential (web-server based) and public (browser-based or native-on-device) applications and the Authorization Code Grant and Implicit Grant methods for acquiring access tokens. If your application is web-server based (confidential), use the Authorization Code Grant method. If your application is browser-based or is a native app on devices (public), use the Implicit Grant.

This authorization method is for applications with a back-end server (i.e., web-based, or confidential in OAuth2 terms). It is the more secure method for acquiring access tokens and Gloebit strongly recommends using it if at all possible.

Your application first uses the Authorize endpoint with a response_type of "code". Gloebit authorizes your user and gets approval for your application to access the user's Gloebit resources, then returns an authorization code via a redirection to your application's redirect URI.

Next, Your application's server extracts the authorization code and posts it to the Exchange for Access Token endpoint for the access token. The security in this method comes from your server providing its OAuth secret during the second step and the access token being returned to your server in the body of the POST response.

For added security, your application should send a "state" parameter to the Authorize endpoint and check it against the returned "state" value (to help prevent CSRF attacks). Plus, you should provide callback URI prefixes in the Authorization fields of your applications configuration page, preferably HTTPS type. Gloebit checks redirect URIs (provided to the Authorize endpoint) against the application's prefixes.

This authorization method is for browser-based applications or applications that run natively on the device (both considered public in OAuth2 terms). Of the two methods that Gloebit supports for acquiring access tokens, it is the less secure because it delivers the access token via the redirect URI and it does not use a secret for your application. Gloebit sets some additional constraints when using this method.

Your application uses only the Authorize endpoint with a response_type of "token". Gloebit authorizes your user and gets approval for your application to access the user's Gloebit resources, then returns the access token via a redirection to your application's redirect URI. Your application extracts the access token from the URI's fragment.

Per the OAuth2 spec, Gloebit requires that you provide callback URI prefixes in the Authorization fields of your application's configuration page and Gloebit checks the authorization request's redirect URI against the prefixes. Additionally, we require your redirect URI use HTTPS instead of HTTP.

For added security, your application should send a "state" parameter to the Authorize endpoint and check it against the returned "state" value (to help prevent CSRF attacks).

Gloebit does two things during a call to the Authorize endpoint. First, it logs the user in to Gloebit, if necessary. Second, it prompts the user to approve your application's access to the user's resources. By default, the approval step always occurs, meaning your user will always see a Gloebit page asking for approval when your application uses the endpoint.

The endpoint's approval_prompt parameter allows your application to have Gloebit conditionally prompt the user. It has two possible values, "force" and "auto":

Authorize - approval_prompt: "force"

Using "force" with approval_prompt causes Gloebit to always prompt the user for access approval. It also causes Gloebit to always generate a new access token (for the combination of application, user, and scope) and discard an existing access token.

It is the default value for the parameter.

Authorize - approval_prompt: "auto"

Using "auto" with approval_prompt causes Gloebit to prompt the user for access approval only if we do not have an existing access token (for the combination of application, user, and scope). If an access token matching the endpoint request's parameters exists, Gloebit will return that access token and might not prompt the user. If no matching access token exists, Gloebit will prompt the user and generate a new access token.

Note: Currently Gloebit does not have a setting for users to always require approval, but we may add one. In the future, with such a setting, a user can choose to force seeing the approval page for your application. However, if you use "auto", Gloebit might still create a new access token only if necessary.

Your application can use Gloebit's Identity service to let Gloebit manage your user accounts. Using this service saves you the trouble of building a login/authentication system. Your users would login via Gloebit to be authenticated, where they can either provide Gloebit login credentials (email + password) or authenticate via Facebook, Google+, Twitter, or LinkedIn.

With this service, after using the Authorization service you would use the Get User ID endpoint to retrieve your user's Gloebit ID. Your application can then use the ID to track the user.

Gloebit user IDs are UUIDs. The service provides them as a string in their canonical form:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

where each "X" represents a hexadecimal number. The lengths of the sequences are 8, 4, 4, 4, and 12. Thus, each user ID is 36 characters total.

Your application can use Gloebit's character service to create and manage characters (or personas or entities or ...) for your users. Each user can have multiple characters in the system. The service allows for storing, retrieving, and editing character details.

The service supports combining with the other Gloebit services. The Inventory service has character-specific endpoints for products. The Digital Currency service allows product purchases to be directed to a character's inventory. Endpoints supporting characters require a character ID. Use the Get List of Characters to get IDs for all of a user's characters.

Gloebit character IDs are UUIDs. The service provides them as a string in their canonical form:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

where each "X" represents a hexadecimal number. The lengths of the sequences are 8, 4, 4, 4, and 12. Thus, each character ID is 36 characters total.

Your application can use Gloebit's Inventory service to create and manage users' inventories and entitlements. The service supports storing products and items in user and character inventories for your application. Products are defined in the Gloebit system whereas items are defined on-the-fly by your application. Generally, using products provides a basic inventory system and using items provides more advanced inventory possibilities.

The first group of Inventory endpoints below are for products. The second group of Inventory endpoints are for items. Note that all inventory endpoints apply to a single application's inventories and there is no inventory sharing between applications in the Gloebit service.

Products in the Inventory service are just names. In a user's or character's inventory, each product can have a count/quantity associated with it, and nothing more. Thus, products provide a basic inventory service akin to storing entitlements. (See the items section if you require storing more information.)

Products are defined per-application, on the application's configuration page. The third group of fields on the page show your application's existing products and let you add new products. (Follow the link for explanations on the product fields on the configuration page.)

Product Names

Gloebit references products by their names, meaning the endpoints require the name of the product to act upon. Thus, within an application all product names need to be unique. Because the Inventory service partitions by application, different applications can have the same product names and the products will be distinct (and not shareable between the applications).

If you change a product's name, the change will not propagate to your users' inventories. They will contain products by the original name with the same quantity as before the name change. The old-name products will show up in inventory products lists but only the consume operation will work for them.

Grant and Set

The service has endpoints for granting a number of products to an inventory and setting the number of products in an inventory. Granting is synonymous with incrementing the inventory quantity. Setting simply forces the quantity to a value. You can configure whether a product can be grant or set via these endpoints on the configuration page. If disallowed, then the product can only be purchased and consumed. (Purchasing is done via the Transact endpoint in the Digital Currency service.)

Per-Inventory Limits

You can set an upper limit for the number of a product in an inventory (user or character). The service will reject any request that would cause the quantity to go above a product's limit.

Availability

You can mark products as unavailable. The effects of making a product unavailable is limited to the transaction service. It will reject purchases for unavailable products. Existing inventories are not affected by a product's availability and your application can still consume and grant an unavailable product and set its quantity.

User and Character Inventories

The service supports inventories for users and their characters, meaning you can keep an inventory for one of your users and inventories for each of the user's characters at the same time. Gloebit separates the inventories, but your application can share among them via the proper endpoints.

Items in the Inventory systems are dictionaries. Your application defines what to put in each item's dictionary on-the-fly. The service stores all items in folders of the user's inventory. Your application can provide folder names to the endpoints or let them use the default folder.

What to store in the item dictionary is entirely up to your application. Use fields for the states of items, player characteristics, system variants, generalized game state information, or anything your application must track. Gloebit checks for maximum string lengths and maximum number of mappings, so let us know if you hit a limit and have a request for extending them.

As with products, items are store per-application. An item stored by one application cannot be retrieved or edited by another. Also, there are no character-specific items in inventories. Your application can use character-specific folders to separate items among a user's characters.

The Inventory service stores all inventory items in folders. A folder name is simply a string, at most 36 characters. The endpoints accept a folder-id parameter that your application can use to sort items as you see fit. The endpoints will use a default folder (UUID with all 0's) if your application excludes the folder-id parameter.

As with products and items, folders are application-specific. The same folder name for the same user from two different applications will create distinct folders.

Your application can use Gloebit's Digital Currency service to handle in-app micro-transactions with gloebits as your digital currency. The service provides an endpoint to look up your user's gloebit balance and an endpoint to request a gloebit payment from your user's account to your account. Both endpoints allow your user to stay within your application. The service also provides an endpoint for redirecting your user to the Gloebit page for purchasing gloebits. The service's three endpoints allow your application to deal entirely in gloebits while Gloebit handles purchasing processes for you.

Engineering Considerations

When integrating this service into your application, you need to consider the following:

• The Transact endpoint only initiates a gloebit payment request. While the endpoint can outright reject a request for various reasons (e.g., insufficient balance) its success indicates the request has been submitted to the final processing queue. Once on the queue the request is likely to succeed, yet it can still be rejected. Thus, your application cannot rely upon the success of this endpoint indicating the transaction has or will succeed, and the final result of the transaction is (typically) not determined until after the endpoint returns to your application.

  If your application depends upon knowing precisely if or when the transaction succeeds or fails, you want to use the Transact callback URLs. Gloebit accesses these URLs to indicate when the transaction finally succeeds or fails. The callbacks are useful for triggering delivery of items within your application or to our inventories. For product transactions, the callbacks also indicate when a product has been delivered to the user's inventory (or that it will not be).

• If your application is not using products (in the Gloebit inventory service) and you need to manage asset delivery for transactions, then you should use the Transact callback URLs. They allow your system to ensure transactions are fully committed before delivering assets.

• The Transact endpoint supports your application including a transaction ID. We strongly suggest you include this ID and, if possible, have it be a UUID. It is very useful in case any disputes occur.

  The Transact endpoint also supports a name for the user on your application. This field can be useful when a single user can have more than one character on an application. The user name is included in the user's transaction history log.

• The Transact endpoint does not support user-to-user transactions. If you are interested in enabling them, please contact us.

• If you are using a submit button for transactions, we suggest you make the button inactive upon submission. This will help avoid double posting while the new page is loading.

• We provide the Balance endpoint so your application can retrieve a user's gloebit balance and display it for the user. Your application can also use the endpoint to check a user's balance before requesting a purchase. Some users may object to this feature's ability to expose gloebits balances. For this reason, Gloebit created a separate scope, "balance", for this endpoint. However, at this time, users are not able to block the endpoint without blocking the entire application access approval. Because Gloebit may yet add a user capability that would effectively block this endpoint, we recommend that your application not depend upon this endpoint being available for all users.

• The Purchase gloebits endpoint is for redirecting your user to the Gloebit site. If you provide an OAuth Key alias in the URL, Gloebit will add trackback links to your application.

Business Considerations

• The service is designed to let your applications use gloebits as their only currency. We suggest you price your products in gloebits and do not show an estimated USD cost. (In our experience, monetization decreases when a USD price is shown.)

• The service includes full transaction histories and provides dispute resolution for all parties on the Gloebit website. Our transaction history includes the transaction ID your application provides. We strongly suggest your applications include transaction IDs to help with bookkeeping and resolving disputes.

• Gloebit deposits the gloebits you earn from your application's transactions into your merchant Gloebit account. See this service's section on the Gloebit Services Overview page for more information on handling earned gloebits.

• The service does not support user-to-user transactions at this time. Please contact us if your business is interested in this feature.

The Transact endpoint is not atomic. It returns either when it knows the transaction cannot be serviced or when Gloebit has queued the transaction request because it has a very good chance at succeeding. If your application is server-based and it needs precise information about the transaction's eventual success or failure or a means to later reject a transaction (e.g. because your purchasing system is also not atomic), then it can use the optional asset callback URL parameters.

Optional

These parameters are optional because they are generally not necessary for product transactions. Gloebit will deliver the product to the user's inventory only when the transaction finally succeeds. You can also omit the parameters if your application has a use case where knowing that the request will likely succeed is sufficient.

URLs

Each parameter is a URL that Gloebit will access at specific stages in processing the queued transaction request. Only URLs accessible from the Gloebit system will work. Browser and native apps cannot use these parameters.

Callbacks

Gloebit will access the URLs with GET requests and will not include any parameters. The URL should include any information your server requires, such as transaction IDs. We suggest using HTTPS URLs for the callbacks.

Each URL access will be blocking, meaning Gloebit waits for your server's response and your server should respond in a timely manner. Additionally, while processing a transaction, Gloebit might access a URL more than once. Your endpoints for these callbacks need to be idempotent and properly handle multiple calls for a transaction.

You can find further details about when each URL can be called in relation to the other URLs and the original Transact request in their descriptions below.

Responses

Your server needs to return a JSON array with 1 or 2 elements to each of the callbacks. The first element is a Boolean indicating whether your server wants to proceed with the transaction. The second element is a string providing status information from your server. Currently the values of the elements affect only Gloebit's "enact" processing.

Transact Parameter: asset-enact-hold-url

Gloebit accesses this URL after it has acquired all holds necessary to process the transaction and is ready to enact it. The transaction is almost guaranteed to succeed at this point, but Gloebit can still roll it back, particularly if your application needs Gloebit to cancel the transaction.

Your application's server can use the response to tell Gloebit to cancel the transaction and roll it back. Your server can also tell Gloebit its processing is pending, in which case Gloebit will access the URL again later. Here are the response options:

With respect to the Transact call and the other callbacks, Gloebit may access this URL before the Transact call has returned (in which case it will return "success: true"), it will access the this URL before accessing the Consume URL, it might not access this URL before accessing the Cancel URL, it might never access this URL in the Cancel URL case, and it might access this URL again after accessing the others. To be safe, your server should not depend on any particular interleaving.

Transact Parameter: asset-consume-hold-url

Gloebit accesses this URL after it has consumed the enacted holds and committed the transaction. At this point, the transaction is complete and can not be rolled back.

Gloebit currently ignores any response to this callback. Your server should send a JSON response of "[true]" to prevent future incompatibilities.

With respect to the Transact call and the other callbacks, Gloebit may access this URL before the Transact call has returned (in which case it will return "success: true"), it will access this URL only after receiving a True response to an enact callback, and this URL and the Cancel URL are mutually exclusive per transaction.

Transact Parameter: asset-cancel-hold-url

Gloebit accesses this URL after it has canceled the enacted holds and effectively canceled the transaction. In parallel with this access, Gloebit will be rolling back any enacted changes.

Gloebit currently ignores any response to this callback. Your server should send a JSON response of "[true]" to prevent future incompatibilities.

With respect to the Transact call and the other callbacks, Gloebit may access this URL before the Transact call has returned, it likely will not be called if the Transact call returns "success: false", it may access this URL before the Enact URL and possibly without ever accessing the Enact URL, it will access this URL if your response to the Enact URL cancels the transaction, and this URL and the Consume URL are mutually exclusive per transaction.

There are many ways to handle delivery of purchases, allowing the merchant/developer to decide what is best for their application.
If your application is using the Product Inventory Service:

• See the Product Transact Parameters section which will automatically handle delivery of your product to the user or character as part of the transaction. This is the simplest way to utilize our services.

• Prior to Transact request --- You are welcome to deliver digital goods prior to making the Transact request if you are willing to have some leakage or handle reversal of delivery on failure. We recommend you check a user's balance to ensure that the user has enough gloebits in his/her account for the purchase. There is no guarantee that the purchase will succeed, but if your application allows purchases during a live-action game, you may prefer some leakage over making a user wait until the transaction completes.
• Upon successful response from Transact request --- Once the system enacts all transfers involved, it returns success. The transaction is not yet committed and can still be rolled back, but that is unlikely. This is a great time to deliver goods, and still very simple. Upon a Transact failure response, the action your application takes should be dependent on the message details. Some possibilities include retrying the Transact call, attempting to fix any problems on the application end, or asking the user to purchase enough gloebits to afford the purchase.
• Upon Transact Callback of asset-enact-hold-url --- This is a similar state as when the Transact request returns success. The transfer has been made to all balances, but has not been committed and can still be rolled back. The transaction processor waits for a response from this url before committing the transaction. Using this callback is a great way to tie in delivery in a way where if delivery of the goods fails, then the gloebit transaction is rolled back. A return of true from this url should mean that you have delivered the goods, and false means you have failed permanently in an attempt to deliver and we should roll back the gloebit transaction. If we receive a response of false, after rolling back the transaction, we will call the asset-cancel-hold-url callback if one has been supplied.
• Upon Transact Callback of asset-consume-hold-url --- If you are looking to be as conservative as possible with delivery of your digital goods, then you may decide to handle delivery upon receiving this callback; however, this creates the risk that a user is charged gloebits and your system fails to deliver the goods. We recommend that the best conservative method is to begin or queue delivery with the asset-enact-hold-url and complete or commit delivery with the asset-consume-hold-url. This callback means the transaction has been fully completed and committed. It can not be canceled or rolled back at this point and the gloebits have been delivered to the merchant/developer account controlling the application that requested the transaction.
• Upon Transact Callback of asset-cancel-hold-url --- If at any point, you receive this callback, the transaction has failed and is being or has been rolled back. If you have not delivered your goods, don't. If you have begun delivery of your goods, then cancel processing of that delivery. Once you receive the asset-consume-hold-url callback, you can rest assured that you will not receive the asset-cancel-hold-url for this transaction.

• While transactions cannot be rolled back once committed, that does not mean that delivery of gloebits cannot later be reversed. We have to deal with fraud and disputes just like any other payment service. We do our best to insulate our partners from fraud, however, there are situations where we will need to place a hold on or reclaim gloebits. For instance, if gloebits sent to you were fraudulently purchased, or if a user disputes the transaction where that user paid you those gloebits, then we may have to take action. For further details, please read the Merchant Terms of Service for Gloebit.

• For information regarding how to get started with your merchant account and test in our sandbox, please see the Getting Started Guide. It's fast and free.
• For information on how to configure the API Settings for your application, please see the Application Configuration Instructions.
• For code level details regarding integration, please visit our API and Code Examples page.
• For instructions on moving your application from sandbox to production when you are ready to release, please visit our Going Live page.
• Gloebit uses OAuth2 in its Authorization service. If you are new to using OAuth2, here is a great, simple summary from Aaron Parecki.

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

• "missing domain"
• "unknown consumer"
• "unknown user"
• "unknown token"
• "token has expired"

• {"success":False, "reason":"unknown token"}

Failure can happen for many reasons including:

• The fields of the dictionary posted for the Transact call are non proper.
• The customer's Gloebit account is not authorized to spend gloebits
• The application is not authorized as a merchant to receive gloebits.
• The application does not have Transact authorization from the customer.
• {"success":False, "status":"failed", "reason":"transaction already created"} - Race condition possible if transaction is submitted multiple times at nearly the identical time.
• {"success":False, "status":"queuing-failed"} - The attempt to queue the transaction for processing failed.
• Enacting the balance adjustments failed (likely customer does not have enough available gloebits)
• If using the Product Inventory System & Product Transact Parameters, enacting of the product delivery failed.
• If we could not enact balance transfers due to issues such as a user not having a sufficient balance not already enacted for other purchases, or your merchant/developer access token being invalid or not containing scope to cover transactions.

Some API features on the roadmap are

• Application specific sub-currencies or soft currencies
• Management and consumption of resources (brick, wood, mineral, etc) in application
• User-to-user transactions

If these, or any other features are important to you, please contact us to help us prioritize or register as a potential future feature beta tester.