Quickstart

Begin is the most elegant way to build Functional Web Apps. The Begin API gives developers complete control over every aspect of the Begin platform.

1. Register a client_id
2. Issue an access_token
3. Install an API client for Node or Deno

Node

Bash

npm i @begin/api

JavaScript

import { App } from '@begin/api'

Deno

JavaScript

import { App } from 'https://api.begin.com/deno/begin@latest/mod.ts'

Authentication

The Begin API implements oAuth 2.0 Device Flow.

Device Flow Overview

1. Your app requests device and user verification codes and gets the authorization URL where the user will authenticate with Begin.
2. The user authenticates.
3. The app polls for the user authentication status. Once the user has authorized, the app will be able to make API calls with a new access_token.

Step 1: App requests the device_code

Your app requests a user code and verification URL that the app will display to the end user to authenticate in the next step. This request also returns a devicer_ code that the app will use to receive an access_ token.

Request

POST /devicecode
Host: api.begin.com
Content-Type: application/x-www-form-urlencoded

client_id=xxx

Body Parameters

All responses are application/json.

Response

{ 
  "device_code": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "user_code": "XXXXXXXX", 
  "verification_uri": "https://api.begin.com/auth" 
}

Step 2: Prompt the user to authenticate

Your device will show the user verification code and prompt the user to enter the code at https://api.begin.com/auth?user_code=XXXXXXXX.

Step 3: App polls to check if the user authenticated

Your app will make device authorization requests that poll POST https://api.begin.com/token, until the device and user codes expire or the user has successfully authorized.

Request

POST /token
Host: api.begin.com
Content-Type: application/x-www-form-urlencoded

client_id=xxx&device_code=xxx

Body Parameters

Response

{ 
  "access_token": "xxx",
}