Authentication Credentials Print

Interacting with VocalCola through the API requires a valid App public+private key pair. 
At this time, Apps can not be automatically created.  Submit a support ticket if you would like your own keys for the VocalCola API.
Be careful not to expose your Private Key, or others may be able to make requests as your App.

Authenticated API Requests

Use the Authorization: Bearer header to make authenticated API requests.
Following Bearer should be a base64 encoded string of period separated values, starting with your app's public key and private key.
You will usually also include a User Token, unless making the initial request to create a User Token from an Authorization Code.
This may also be followed by a Plan Key, if you're guest managing a plan that the User has access to.

Authorization: Bearer base64(pubKey.privKey)
Authorization: Bearer base64(pubKey.privKey.userToken)
Authorization: Bearer base64(pubKey.privKey.userToken.planKey)

Request Authorization from a User

Send your user to:

https://portal.vocalcola.com/user/apps/authorize.php
    ?response_type=code
    &scope=[REQUESTED-SCOPES]
    &client_id=[APP-PUBLIC-KEY]
    &redirect_uri=[RETURN-ADDRESS]

They will be presented with an explanation page. Once accepted, they will be sent to the URI given in redirect_uri, with the added parameter code=[AUTH-CODE].
This code expires after a few minutes.

Create a User Token

After receiving an auth code, quickly send a server-side request like this:

POST https://api.vocalcola.com/v0/token/
{
    'grant_type': 'authorization_code',
    'code': '[AUTH-CODE]',
    'redirect_uri': '[RETURN-ADDRESS]',
}

The redirect_uri must be the same as what you submitted with the initial User Auth request.
The response will be similar to this:

{
    'access_token': '[BEARER-TOKEN]',
    'user_token': '[USER-TOKEN]',
    'scope': '[USER-APPROVED-SCOPES]',
    'comment': 'Build your own access token: base64 encode [app_id].[app_secret].[user_token]',
    'stamp': '[UTC TIMESTAMP]',
}

access_token is a pre-formatted Authorization: Bearer key that uses your credentials and the new User Token.
scope is a list of scopes the user agreed to.

Get Info

You can use https://api.vocalcola.com/v0/me/ to see details about the information in your current Bearer token.
If you have included a User Token, you can use /v0/me/plans/ to see a list of Plans that the selected User can guest manage.