Using Bootstrap API

Use this tutorial to set up a Playbook organization and user in one go, using your partner integration.

Why Use Bootstrap API

• All-in-One Call: Create (or find) an organization and user in a single HTTP request.
• Idempotent: Re-run safely for the same partner_user_id without creating duplicates.
• Instant Login: Get back a magic login link so your user can jump right into Playbook.

Prerequisites

1. Integration Token (integration_token): Secret token Playbook issues to your backend.
2. Partner User ID (partner_user_id): Your app's unique user identifier (e.g., internal database ID).
3. Bootstrap Endpoint URL: POST https://be.playbook.com/api/v1/bootstrap.

Endpoint & Authentication

POST /api/partner/bootstrap
Authorization: Bearer <integration_token>
Content-Type: application/json

Request Payload

Field	Type	Required	Description
partner_user_id	string	yes	Your unique ID for this user.
user.email	string	yes	User's email address.
user.name	string	yes	Full name of the user.
organization.name	string	yes	Name of the organization to create or retrieve.
boards	array	no	(Optional) List of boards & nested assets.

Sample Request Body

{
  "partner_user_id": "user-12345",
  "user": {
    "email": "jane@client.com",
    "name": "Jane Doe"
  },
  "organization": {
    "name": "Acme Corp"
  },
  "boards": [
    {
      "title": "Homepage Assets",
      "assets": [
        {
          "url": "https://cdn.partner.com/images/hero.jpg",
          "filename": "hero.jpg",
          "description": "Main banner"
        }
      ]
    }
  ]
}

Successful Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "redirect_url": "https://www.playbook.com/magic_login?token=XYZ123",
  "access_token": "USER_ACCESS_TOKEN"
}

• redirect_url: Magic login link your frontend will redirect the user to.
• access_token: OAuth2 token that should be stored and used for making API calls on behalf of this user. Use it to fetch or create data in Playbook without requiring the user to authenticate again.

Error Handling

• 401 Unauthorized: Invalid or missing integration_token.
• 422 Unprocessable Entity: Missing required fields or invalid data.
• 500 Internal Server Error: Unexpected server problem.

Next Steps

• Redirect the user's browser to the redirect_url for automatic login.