BOSON REST API documentation

Warning

This is alpha-development version of API and may be the subject to change.

Authentication

Oauth2

GET /oauth2/authorize

Users will be sent to this URL to authorize your application. Once authorized, the user will be redirected to redirect_uri with a url encoded authorization code that will be required in the token endpoint

Parameters:
  • client_id (string) – The application’s client id
  • redirect_uri (string) – The URL that the user will be redirected to after authorization. Must match whitelist
  • scope (string) – requested scopes
  • state (string) – Value passed back to the redirect_uri for the client to handle state / prevent XSRF
  • response_type (string) – The authorization type (code)

Note

at this point the User may change the requested scopes, client should check scopes obtained from the token endpoint.

POST /oauth2/token
Form Parameters:
 
  • grant_type – [client_credentials, authorization_code, refresh_token]
  • client_id
  • client_secret
  • code
Response JSON Object:
 
  • access_token (string) –
  • refresh_token (string) –
  • scope (list) – for simplified client flow the granted scope will always be included
  • token_type (string) –
  • expires_in (int) –

supported grants:

  • authorization code <https://tools.ietf.org/html/rfc6749#section-1.3.1>
  • client credentials <https://tools.ietf.org/html/rfc6749#section-1.3.4>
  • token refresh <https://tools.ietf.org/html/rfc6749#section-6>

Scopes

verification list

name
phone
twitter
facebook
google
github
btcjam
id_document
ethereum
all

scopes

name description
status:[verification-name] status of given verification
require:[verification-name] same as status: but requires given verification to be provided by resource owner and approved by boson before proceeding in oauth flow

Resources

POST /api/v1/user/(string: app_user_id)
Request JSON Object:
 
  • fields (list) –
POST /api/v1/user/me

/me is a special endpoint that translates to the user ID of the person whose access token is being used to make the request.

json schema

{
    "$schema": "http://json-schema.org/draft-06/schema#",
    "title": "User",
    "type": "object",
    "properties": {
        "id": {
            "description": "scoped user id",
            "type": "string"
        },

        "status": {
            "description": "status of verifications ( scope status:[verification-name])",
            "type": "object",
            "patternProperties": {
                ".+": {
                    "type": "object",
                    "properties": {
                        "status": {"enum": ["verified", "pending", "unverified"]}
                    },
                    "required": [ "status" ]
                }
            }
        },
    "required": ["id"]
}

Examples

import os
from requests_oauthlib import OAuth2Session
from oauthlib.oauth2 import BackendApplicationClient

client_id = os.getenv('client-id')
client_secret = os.getenv('client-secret')
token_url = "https://app.boson.me/oauth2/token"

sess = OAuth2Session(
    client=BackendApplicationClient(client_id=client_id)
)

token = sess.fetch_token(
    token_url=token_url,
    client_id=client_id,
    client_secret=client_secret
)

print(token)

resp = sess.post("https://app.boson.me/api/v1/user/me")

print(resp.json())
import os
import logging
from binascii import hexlify

from flask import Flask, render_template_string
from flask_dance.consumer import OAuth2ConsumerBlueprint
logging.basicConfig(level=logging.DEBUG)

token_url = "https://app.boson.me/oauth2/token"
client_id = os.getenv('client-id')
client_secret = os.getenv('client-secret')

boson = OAuth2ConsumerBlueprint(
    "boson", __name__,
    client_id=client_id,
    client_secret=client_secret,
    base_url="https://app.boson.me",
    token_url=token_url,
    authorization_url="https://app.boson.me/oauth2/authorize",
    scope=['require:phone'],

    auto_refresh_url=token_url,
    auto_refresh_kwargs={
        'client_id': client_id,
        'client_secret': client_secret,
    }

)


app = Flask(__name__)
app.secret_key = hexlify(os.urandom(24))

app.register_blueprint(boson, url_prefix="/login")


@app.route("/")
def index():
    if not boson.session.authorized:
        return render_template_string("""
            <a href="{{url_for('boson.login')}}"> Verify! </a>

        """)

    resp = boson.session.post("/api/v1/user/me")
    resp_json = resp.json()
    print(resp_json)
    return render_template_string("""
        <p>user id: {{uid}}</p> <p>phone status: {{status}}</p>
    """, status=resp_json['status']['phone'], uid=resp_json['id'])


if __name__ == "__main__":
    app.run()

Changelog

  • client_id for authorize endpoint should be a string, scope
  • examples
  • new domain