Core API Walkthrough

core.py

#!/usr/bin/env python
from binascii import unhexlify
from brave.api.client import API
from ecdsa import SigningKey, VerifyingKey, NIST256p
from flask import Flask, redirect, request, url_for
from hashlib import sha256

app = Flask(__name__)


# Creates a SigningKey or VerifyingKey from a hex string
def hex2key(hex_key):
    key_bytes = unhexlify(hex_key)
    # The keys can be distinguised by length
    if len(hex_key) == 64:
        return SigningKey.from_string(key_bytes, curve=NIST256p,
                hashfunc=sha256)
    elif len(hex_key) == 128:
        return VerifyingKey.from_string(key_bytes, curve=NIST256p,
                hashfunc=sha256)
    else:
        raise ValueError("Key in hex form is of the wrong length.")


@app.before_first_request
def attach_api():
    # app_key.txt is the application's private key, in hex form
    with open('app_key.txt', 'rb') as f:
        app_hex = f.read()
        app_hex = app_hex.replace(b'\n', b'')
        app_key = hex2key(app_hex)
    # server_key.txt is the server's public key, in hex
    with open('server_key.txt', 'rb') as f:
        server_hex = f.read()
        server_hex = server_hex.replace(b'\n', b'')
        server_key = hex2key(server_hex)
    # app_id.txt is the application's identifier
    with open('app_id.txt', 'rb') as f:
        app_id = f.read()
        app_id = app_id.replace(b'\n', b'')
    # Save the Core API object on the application for later access
    app.core_api = API('https://core.braveineve.com',
            identity=app_id,
            public=server_key,
            private=app_key)


@app.route('/login/')
def login():
    token = request.args.get('token')
    if token is not None:
        # Access the /api/core/info endpoint
        info = app.core_api.api.core.info(token=token)
        # The API responses are accessible both as object attributes or as
        # dictionary keys.
        character_name = info.character.name
        # character_name = info['character']['name']
        return "Hello {}".format(character_name)
    else:
        return "Sorry, login failed"


@app.route('/')
def index():
    # The _external argument makes the returned url by fully qualified
    result_url = url_for('login', _external=True)
    print(result_url)
    # Ask Core for a URL to redirect the user to. You can give different URLs
    # for Core to redirect the user to on authentication success or failure.
    core_response = app.core_api.api.core.authorize(
            success=result_url,
            failure=result_url)
    # Send the user to Core for authentication
    print(core_response)
    core_url = core_response['location']
    print(core_url)
    return redirect(core_url)


if __name__ == '__main__':
    app.debug = True
    app.run()

gistfile1.md

#Core API Walkthrough

##How the API works internally When you register an application in Core, an [Application][app_file] record is created in the database. When a user wants to sign in to your app, your app asks for a unique login URL to redirect the user to. The user goes there, enters their credentials, chooses the characters to grant access to, then clicks the login button. Core then redirects the user back to your app with a special 'token' argument in the URL. Your app can then use that token to access the user's information in Core. When the user clicked the login button (just before being redirected back to your app), Core looked up the Application and created an [ApplicationGrant][app_file] record. This grant stores what permissions a user has granted to your app, and are listed in the "Authorized" tab in the applications section of the Core interface. [app_file]: https://github.com/bravecollective/core/blob/develop/brave/core/application/model.py

All of the messages back and forth between your app and the server are signed with the originator's private key, and verified with the appropriate public key. If you're encountering errors with an external Core instance, I highly recommend setitng a local instance up and turning the logging options up to figure out where the problem is occuring.

##Using the API

###Prep work First you need to generate an ECDSA keypair. You can either do it in Python using the ecdsa package or with the OpenSSL shell utilities. How to generate keypairs. First you need to have an application registered in Core. In the Core interface, click "Applications" in the sidebar, then go to the "Manage" tab. Then you can click the "Register Application" button. Fill in the fields under the "General" tab, and then under the "ECDSA Key" tab put the public (aka verifying) key in hex format in the textbox. The help text lies and it doesn't accept PEM encoded keys. After that you can click the "Save" button.

Now you need to get your application's identifier and the server public key. In the list of your applications (under the "Management" tab) click on your newly created application. Save the application id (short hex string) and the server public key (pick the format that's most convenient for you) somewhere.

###Writing the app