App Clients

An App Client represents the external system or application that's calling Nitro APIs. Each system that integrates with Nitro should have its own App Client to ensure the identification, authentication, and management of API access. Typically, the number of systems you have calling Nitro APIs is the number of App Clients you need for your program. A maximum of 5 are allowed.

Token Types

Token	Use	Restrictions	Expiration and Renewal	Exposure
Nitro API (NWT)	Allows access to public Nitro APIs Created via App Client credentials grant	Every API method is allowed without restriction	A token creation request may include expires_in and defaults to ~24 hours A token should be renewed as necessary	Must NEVER be exposed publicly for ANY reason May be shared across multiple threads and multiple user sessions
Gamification (GWT)	Allows access to an embedded block for a specific gamification user Created via API call and requires your platform to authenticate/authorize the gamification user	No access to public APIs	A token creation request may include expires_in and defaults to ~24 hours. Best practice is slightly longer than your platform session. A new token should not be requested with each user session. Your code should 1) request a token, 2) listen for a 401 https code indicating the token is invalid, and then 3) request a new token when you receive the expiration message. A token should NOT be renewed without re-authenticating the gamification user on your platform	May be exposed publicly without restriction Cannot be shared by different user sessions
Legacy OAuth	Grants acess to web components

Token Creation

In your application, include the code to generate an access token.

Token	Details
Nitro API (NWT)	API Credentials granted via POST https://api.bunchball.com/oauth/token Requires an App Client created in Nitro Studio Nitro Studio Implicitly created at Studio login Restricted to the logged in admin user Grants access to public APIs via the API Documentation link
Gamification (GWT)	API call via POST https://api.bunchball.com/gamification-token Requires a valid Nitro API token (NWT) Restricted to a specific gamification user Authentication/authorization of the gamification user is the responsibility of the caller When you request a gamification token for a user that doesn't already exist in Nitro, the user is automatically created. To prevent automatic user creation: Pass upsertUser=false in your token request. The request will return a 404 error if the user doesn't exist instead of generating a token and creating the user. When you get a 404 error, call PUT /users/{userId} to add the user to Nitro and enroll them in groups, the award account, etc. Retry the gamification token request once the user has been created. Access will be denied if the token does not meet security requirements.

Token

Details

Nitro API (NWT)

API

Credentials granted via POST https://api.bunchball.com/oauth/token
Requires an App Client created in Nitro Studio

Nitro Studio

Implicitly created at Studio login
Restricted to the logged in admin user
Grants access to public APIs via the API Documentation link

Gamification (GWT)

API call via POST https://api.bunchball.com/gamification-token

Requires a valid Nitro API token (NWT)
Restricted to a specific gamification user
Authentication/authorization of the gamification user is the responsibility of the caller
When you request a gamification token for a user that doesn't already exist in Nitro, the user is automatically created. To prevent automatic user creation:

Pass upsertUser=false in your token request.
The request will return a 404 error if the user doesn't exist instead of generating a token and creating the user.
When you get a 404 error, call PUT /users/{userId} to add the user to Nitro and enroll them in groups, the award account, etc.
Retry the gamification token request once the user has been created.

Access will be denied if the token does not meet security requirements.

Create an App Client

Open Nitro Studio > Configuration > App Client.
Click New App Client.

You cannot edit an existing App Client.

In the Name field, enter a descriptive name that does not contain spaces.
The name must be unique across all sites in the environment. In Sandbox, you may need to preface the name with your company or some other unique identifier as there are multiple internal (Nitro) and external (customer) test sites in the environment.
Click Save.

Use caution if you delete an App Client as external code may depend on this connection.

App Client Examples

Example 1: You have one application with the Impact block embedded in it.

Create one App Client named for the application
On user login to the application, create a Gamification Token (GWT) for the block embed
When a user interacts with the application, send actions via POST /users/{userId}/actions

Example 2: You have Impact embedded in your primary application and send actions from multiple other services.

Create one App Client for the application
- On user login to the application, create a Gamification Token (GWT) for the block embed
Create one App Client per unique service that sends actions to Nitro
- Make calls to POST /users/{userId}/actions

Example 3: Your program uses custom API calls.

Create one App Client per backend application
- Make the appropriate calls to the public Nitro API
- NEVER expose the Nitro API Token (NWT) publicly
- Do not include the token on the HTML page
- Do not make AJAX calls directly from the browser to the Nitro API