---
updatedAt: 2026-04-30T11:04:59.000Z
agentTools:
  projectIndex: https://docs.bkbn.com/llms.txt
---

# /auth/token

Authenticates a client using their credentials and returns a JWT token. This endpoint is used to obtain authentication tokens for subsequent API calls. Requires a valid client ID and secret. Returns an authentication response containing the JWT token and related authentication details.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "BKBN Sync API",
    "description": "API connector for customer applications.",
    "version": "2.16.0"
  },
  "servers": [
    {
      "url": "http://sync-dev.bkbn.com",
      "description": "Generated server url"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Auth",
      "description": "Controller for authentication operations"
    },
    {
      "name": "Webhook Events",
      "description": "Event payloads BKBN POSTs to your callback URL. You receive these; you do not call them."
    }
  ],
  "paths": {
    "/auth/token": {
      "post": {
        "tags": [
          "Auth"
        ],
        "description": "Authenticates a client using their credentials and returns a JWT token. This endpoint is used to obtain authentication tokens for subsequent API calls. Requires a valid client ID and secret. Returns an authentication response containing the JWT token and related authentication details.",
        "operationId": "authenticate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuthRequest": {
        "type": "object",
        "description": "Client-credentials exchange. The returned token is sent as a Bearer token on every other endpoint.",
        "properties": {
          "clientId": {
            "type": "string",
            "description": "Client id issued to your integration by Backbone."
          },
          "secret": {
            "type": "string",
            "description": "Client secret issued alongside the client id."
          }
        },
        "required": [
          "clientId",
          "secret"
        ]
      },
      "AuthResponse": {
        "type": "object",
        "description": "Issued access token.",
        "properties": {
          "idToken": {
            "type": "string",
            "description": "JWT to send as `Authorization: Bearer {idToken}` on every other endpoint."
          },
          "expiresIn": {
            "type": "string",
            "description": "Lifetime of the token in seconds, as a string. Re-authenticate before it elapses.",
            "example": "3600"
          }
        },
        "required": [
          "expiresIn",
          "idToken"
        ]
      },
      "VisualsReadyEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "orderId",
          "assignmentId",
          "visualType",
          "product"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "VISUALS_READY"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the webhook was sent.",
            "example": "2023-01-15T12:45:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "visualType": {
            "type": "string",
            "description": "Resource type that is ready. Mirrors the platform resource taxonomy.",
            "example": "POST"
          },
          "product": {
            "type": "string",
            "description": "Product/deliverable that is ready. Mirrors the platform product taxonomy.",
            "example": "GROUND_PHOTO"
          },
          "realEstatePropertyId": {
            "type": "string",
            "format": "uuid",
            "description": "Real estate property id, if applicable."
          },
          "objectReferenceId": {
            "type": "string",
            "description": "Client-supplied object reference, if provided."
          }
        }
      },
      "PhotographerBookedEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "orderId",
          "photographerId"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "PHOTOGRAPHER_BOOKED"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T12:45:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "photographerId": {
            "type": "string",
            "description": "Public id of the photographer (creative) who accepted.",
            "example": "55021"
          },
          "assignmentId": {
            "type": "string",
            "description": "Assignment id, when available.",
            "example": "a1b2c3d4"
          }
        }
      },
      "OrderStatusUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "previousStatus",
          "newStatus"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ORDER_STATUS_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the change occurred on the platform.",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "previousStatus": {
            "type": "string",
            "example": "PLACED"
          },
          "newStatus": {
            "type": "string",
            "example": "IN_PROGRESS"
          }
        }
      },
      "AssignmentStatusUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "previousStatus",
          "newStatus"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ASSIGNMENT_STATUS_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "previousStatus": {
            "type": "string",
            "example": "SCHEDULED"
          },
          "newStatus": {
            "type": "string",
            "example": "IN_PRODUCTION"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "description": "Confirmed shooting start, when available."
          },
          "estimatedDeliveryAt": {
            "type": "string",
            "format": "date",
            "description": "Estimated delivery date (date-only), when available."
          },
          "actionRequired": {
            "type": "string",
            "description": "Action-required detail, when applicable."
          }
        }
      },
      "AppointmentDateUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "scheduledAt"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "APPOINTMENT_DATE_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "scheduledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "New confirmed shooting start. Always present; `null` means the appointment was cleared (reschedule pending).\n"
          }
        }
      },
      "EstimatedDeliveryUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "estimatedDeliveryAt"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ESTIMATED_DELIVERY_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "estimatedDeliveryAt": {
            "type": "string",
            "format": "date",
            "description": "Estimated delivery date (date-only).",
            "example": "2026-07-02"
          }
        }
      },
      "MarketingMaterialsReadyEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "propertyId",
          "targetPlatform"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "MARKETING_MATERIALS_READY"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T12:45:00Z"
          },
          "propertyId": {
            "type": "string",
            "format": "uuid",
            "description": "Real estate property id."
          },
          "targetPlatform": {
            "type": "string",
            "description": "Target platform the materials were prepared for."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "JWT Authentication. Enter your token in the format: Bearer {token}",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "EventTypeHeader": {
        "name": "X-Event-Type",
        "in": "header",
        "required": true,
        "description": "The event name. Matches the `event` field in the body.",
        "schema": {
          "type": "string",
          "example": "ASSIGNMENT_STATUS_UPDATED"
        }
      }
    }
  },
  "webhooks": {
    "visualsReady": {
      "post": {
        "summary": "Visuals ready",
        "description": "Sent when materials (visuals, documents, or other deliverables) are ready for download. On receipt, call the Materials API to retrieve the actual files.\n",
        "operationId": "onVisualsReady",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VisualsReadyEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "photographerBooked": {
      "post": {
        "summary": "Photographer booked",
        "description": "Sent when a photographer (creative) has accepted an assignment.",
        "operationId": "onPhotographerBooked",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhotographerBookedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "orderStatusUpdated": {
      "post": {
        "summary": "Order status updated",
        "description": "Sent when an order transitions between statuses.",
        "operationId": "onOrderStatusUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderStatusUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "assignmentStatusUpdated": {
      "post": {
        "summary": "Assignment status updated",
        "description": "Sent when an assignment transitions between statuses. May also be sent as a same-status nudge carrying refreshed logistics fields.\n",
        "operationId": "onAssignmentStatusUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignmentStatusUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "appointmentDateUpdated": {
      "post": {
        "summary": "Appointment date updated",
        "description": "Sent when an assignment's shooting appointment date changes. `scheduledAt` is always present and is `null` when the appointment was cleared (reschedule pending).\n",
        "operationId": "onAppointmentDateUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppointmentDateUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "estimatedDeliveryUpdated": {
      "post": {
        "summary": "Estimated delivery updated",
        "description": "Sent when an assignment's estimated delivery date changes.",
        "operationId": "onEstimatedDeliveryUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimatedDeliveryUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "marketingMaterialsReady": {
      "post": {
        "summary": "Marketing materials ready",
        "description": "Sent when marketing materials for a property are ready for a target platform.",
        "operationId": "onMarketingMaterialsReady",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MarketingMaterialsReadyEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    }
  }
}
```