Boatfront API

The Boatfront API supports two authentication methods. Choose based on your use case:

All API requests must include an Authorization header:

curl -X GET https://www.boatfront.com/api/listings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Boatfront implements the OAuth 2.1 authorization code flow with PKCE. This is the recommended method for applications that need to access the API on behalf of a user.

1. Register your application

Create an OAuth app in the Broker Portal. You will receive a client_id and client_secret.

2. Generate a PKCE code challenge

PKCE is required for all clients per the OAuth 2.1 specification.

import crypto from "crypto";

const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

3. Redirect to authorize

Send the user to the Boatfront authorization endpoint:

GET https://www.boatfront.com/api/auth/oauth2/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid+listings:read
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

The user will see a consent screen and choose to allow or deny access. On approval, they are redirected to your redirect_uri with a code parameter.

4. Exchange the code for tokens

curl -X POST https://www.boatfront.com/api/auth/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=CODE_VERIFIER"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2...",
  "scope": "openid listings:read"
}

5. Refresh an access token

Access tokens expire after 1 hour. Use the refresh token to get a new one:

curl -X POST https://www.boatfront.com/api/auth/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

6. Revoke a token

curl -X POST https://www.boatfront.com/api/auth/oauth2/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=TOKEN_TO_REVOKE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

PKCE prevents authorization code interception attacks and is mandatory for all OAuth clients — both public (native/MCP) and confidential (server-side).

API keys provide a simpler authentication method for server-to-server integrations where user-delegated access is not needed.

Creating an API key

Generate keys in the Broker Portal → Developer → API Keys. Each key has a configurable expiration and is shown only once upon creation.

Using an API key

Include the key in the Authorization header:

curl -X GET https://www.boatfront.com/api/listings \
  -H "Authorization: Bearer bf_live_abc123def456..."

Scopes control what resources an access token can access. Request only the scopes your application needs.

API requests are rate-limited per client to ensure fair usage. Rate limit information is included in response headers.

Response headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 94
X-RateLimit-Reset: 1713234060

When rate limited, the API returns a 429 Too Many Requests response. Retry after the X-RateLimit-Reset timestamp.

The API returns standard HTTP status codes. Error responses include a JSON body with details:

{
  "error": "A human-readable error message",
  "code": "ERROR_CODE"
}

Boatfront publishes standard OAuth 2.1 and OpenID Connect discovery metadata: