1. Bearn API Quickstart Guide
    1. General API Information
    2. API Endpoints
    3. API Documentation
    4. Authentication
      1. General Testing
      2. Authorized Credentials
  2. Partner Links
    1. The Basics
    2. More Control
    3. Apple and Google Branding
      1. Example
    4. Partner User Reporting

Bearn API Quickstart Guide

General API Information

The Bearn platform is supported by the Bearn APIs. These APIs can be used to create custom flows in other products and to provide useful integration points for our partners and our own internal tooling. These APIs follow the REST convention where requests are made against resources using an http method to infer an action on that resource:

Http Method Resource Behavior
POST /offer/json Create an offer
GET /offer/json Retrieve an offer
PATCH /offer/json Update an offer
DELETE /offer/json Remove an offer

API Endpoints

Bearn provides two API endpoints, one for preproduction environments and one for production:

Environment Endpoint
preproduction https://api.beta.bearnit.com
production https://api.bearnit.com

All examples in this document will use the preproduction endpoint, however both environments are virtually identical with the exception of which version of the API is running on the environment.

API Documentation

API documentation can be found here:

API Documentation

Please register with a new user and verify your email address.

Authentication

General Testing

We provide a quick solution for authentication via the apidocs here: Bearn API Docs. If you don't already have an account, create one or use a social login. If you receive an error, make sure to check your email and verify your email address, then log back into the apidocs. Once you have logged in successfully, you will see all the api docs. This documentation is live, so you can test out all the public APIs from this page. Here's a simple example to make sure you have public access:

Get My Profile

Authorized Credentials

When you are ready to make requests directly from your application, please make an subject: Authorized Credentials Request to our API support team [email protected] Make sure the subject is "Authorized Credentials Request" and provide the following in the body of the email:

  1. Your company's name
  2. Your name
  3. Your email
  4. Your contact phone number
  5. How you intend to use our API
  6. What permissions you require*

*The permissions can be found at the heading of each api listing in our apidoc: (example) partner.create.links

By default, your client credentials can be used to make requests against the API for resources and HTTP methods which do not require any permissions. If you are accessing a resource and HTTP method that requires permissions, and your credentials do not have the appropriate permission, you will receive an HTTP 403 Forbidden. Please make a request to [email protected] to add the appropriate permissions.

To authenticate, you will first need to generate a JWT token by using the appropriate token endpoint:

curl --request POST \ --url 'https://auth.beta.bearnit.com/oauth/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials \ --data 'client_id=YOUR_CLIENT_ID' \ --data client_secret=YOUR_CLIENT_SECRET \ --data audience=http://beta.bearnit.com

The response will be similar to:

{ "access_token": "<JWT.TOKEN>", "expires_in": 86400, "token_type": "Bearer" }

Where <JWT.TOKEN> is a JWT token that (when decoded) stores information similar to:

{ "iss": "https://auth.beta.bearnit.com/", "sub": "[email protected]", "aud": "http://beta.bearnit.com", "iat": 1594770529, "exp": 1594856929, "azp": "1Dwq9VDQG9eKOP5G7IUnKvUUHSH2qqqK", "gty": "client-credentials" }

You can use jwt.io to both preview and verify the token. Note the 86400 expiration is in seconds and equates to 24 hours. THIS VALUE MAY VARY as changes to our platform are made so please track the expiration and make a new request for a token appropriately. Please DO NOT make a request for a token for every call. We will both save money on our bandwidth and reduce unnecessary overhead and reduced security if you follow oauth2 client-credentials conventions.

Now that you have a JWT token, you can add the appropriate header to your client and make API calls as a partner application:

curl -H 'Authorization: Bearer <JWT.TOKEN>' https://api.beta.bearnit.com/offer/json

For non curl clients, you will need to add a request header Authorization with value Bearer <JWT.TOKEN> making sure to replace <JWT.TOKEN> with the token from the authorization response you received in the prior step.

Partner Links

The Basics

When you bring a user to the Bearn platform, you may want to track and mark that user as your user on Bearn. We provide a series of APIs that provide link generation, tagging, and tracking for our partners.

If you are just interested in basic links to the Apple App and Google Play stores, and do not wish to interact with the APIs, please email [email protected] with subject: Bearn Partner Links and provide the following information in the body:

  1. Your company's name
  2. Your name
  3. Your email
  4. Your contact phone number

We will respond with two links, one for the Apple Store and one for the Google Play Store which you can send to your users. When a user clicks one of the links, we will attribute the user in our platform to you as a partner.

More Control

You can control the link generation and tagging process yourself by using our APIs. The following API generates two links, one for the Apple App Store and one for the Google Play Store: https://api.beta.bearnit.com/apidoc/#api-Partner.

The API endpoint requires the partner/advertiser ID, if you do not know what this ID is, please email [email protected] with subject Partner ID and body:

  1. Your company's name
  2. Your name
  3. Your email
  4. Your contact phone number

And we will reply with your partner ID.

You can also pass arbitrary tags in with your link for your own purposes. These tags are available when running conversion or partner user reports.

Partner Links API

Apple and Google Branding

When sharing these links out, you could and probably should use both Apple's and Google's general guidelines for linking to their stores:

App Store Badge

Google Play Badge

Example

Download the Bean App today and start earning by burning calories!

App Store

Google Play

Partner User Reporting

We provide an API for our partners to track conversion of generated links to user signups. Please review the following API:

Partner User Report