API Reference

The DevBar REST API base URL is https://api.devbar.app. All endpoints are prefixed with /api/v1.

Authentication: Endpoints marked Auth required require a Bearer token in the Authorization header: Authorization: Bearer <access_token>

Rate Limits: Most authenticated endpoints allow 120 requests per minute per user. Authentication endpoints (login, register) are limited to 10 requests per 15 minutes per IP. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. When rate-limited you receive a 429 response.

Base URL: https://api.devbar.app/api/v1. EU customers use https://eu.api.devbar.app/api/v1.

Authentication OAuth Device Auth SAML Users Tokens Organisation Workflows Admin Webhooks SCIM WebSocket Request / Response Examples

Authentication

Method	Path	Description	Auth
POST	/auth/register	Register a new user account	—
POST	/auth/login	Sign in and receive access + refresh tokens	—
POST	/auth/refresh	Exchange a refresh token for a new access token	—
POST	/auth/forgot-password	Request a password-reset email	—
POST	/auth/reset-password	Reset password using the emailed token	—
POST	/auth/verify-email	Verify email address with the emailed code	—

OAuth

Method	Path	Description	Auth
GET	/auth/google	Initiate Google OAuth flow	—
GET	/auth/github	Initiate GitHub OAuth flow	—

Device Auth

PKCE flow used by the macOS app: the browser sign-in is bound to a local port and a code challenge.

Method	Path	Description	Auth
GET	/auth/device/authorize?port=&code_challenge=	Start browser sign-in for the desktop app (redirects to the login page)	—
GET	/auth/device/status/:session_id?code_verifier=	Poll whether the browser sign-in has completed	—
POST	/auth/device/complete	Approve the pending device session as the signed-in user	Required
POST	/auth/device/exchange	Exchange the one-time code for access + refresh tokens	—

SAML

Method	Path	Description	Auth
GET	/auth/saml/metadata?org_id=	SP metadata XML for IdP configuration	—
GET	/auth/saml/login?org_id=	Redirect to the organisation's IdP login page	—
POST	/auth/saml/acs	Assertion Consumer Service — receives the SAML response	—

Users

Method	Path	Description	Auth
GET	/users/me	Get the authenticated user's profile	Required
PATCH	/users/me	Update profile fields (name, email)	Required
GET	/users/me/features	List feature flags enabled for the user	Required

Tokens

Method	Path	Description	Auth
GET	/tokens	List all API tokens for the authenticated user	Required
POST	/tokens	Create a new API token	Required
PATCH	/tokens/:id	Rename a token (update its label)	Required
DELETE	/tokens/:id	Revoke a token	Required

Organisation

Method	Path	Description	Auth
GET	/org	Get the authenticated user's organisation	Required
PATCH	/org	Update organisation settings	Required
GET	/org/members	List organisation members	Required
DELETE	/org/members/:userId	Remove a member from the organisation	Required
GET	/org/invitations	List pending invitations	Required
POST	/org/invitations	Invite a user by email	Required
DELETE	/org/invitations/:id	Cancel a pending invitation	Required

Workflows

Method	Path	Description	Auth
GET	/org/workflows	List organisation workflows	Required
POST	/org/workflows	Create a workflow	Required
GET	/org/workflows/:id	Get a workflow by ID	Required
PATCH	/org/workflows/:id	Update a workflow	Required
DELETE	/org/workflows/:id	Delete a workflow	Required
POST	/org/workflows/:id/install	Install a workflow for the current user	Required
POST	/org/workflows/:id/fork	Fork a workflow into your organisation	Required
POST	/org/workflows/:id/publish	Publish a workflow to the marketplace	Required
GET	/org/workflows/:id/runs	List recent runs of a workflow	Required
GET	/marketplace/workflows	Browse published workflows (public, rate-limited)	—

Admin

Method	Path	Description	Auth
GET	/admin/users	List all users (admin only)	Required
GET	/admin/orgs	List all organisations (admin only)	Required
GET	/admin/features	List all feature flags	Required
PATCH	/admin/features/:key	Enable / disable a feature flag	Required
GET	/admin/plans	List available plans	Required
GET	/admin/audit-log	Query the audit log	Required
GET	/admin/email-config	Get email provider configuration	Required
PUT	/admin/email-config	Update email provider configuration	Required
GET	/admin/orgs/:id/saml	Get an organisation's SAML configuration	Required
PUT	/admin/orgs/:id/saml	Create or update an organisation's SAML configuration	Required
DELETE	/admin/orgs/:id/saml	Delete an organisation's SAML configuration	Required
POST	/admin/orgs/:id/saml/test	Validate that the SAML configuration can be loaded	Required
POST	/admin/orgs/:id/saml/scim-token	Generate a SCIM bearer token (shown once)	Required
GET	/admin/audit-log-v2?from=&to=	Query the partitioned audit log by time range (RFC 3339)	Required
GET	/admin/newsletter	List active newsletter subscribers	Required
GET	/admin/metrics/summary	Event counts for a rolling window (hours query param)	Required
GET	/admin/metrics	Stored metric events, optionally filtered by event name	Required

Webhooks

Webhook receivers live at the API root (https://api.devbar.app/webhooks/...), not under /api/v1.

Method	Path	Description	Auth
POST	/webhooks/stripe	Stripe billing events (internal — do not call directly)	—
POST	/webhooks/paddle	Paddle billing events (internal — do not call directly)	—
POST	/webhooks/pagerduty	PagerDuty incident events, routed by ?token=	—
POST	/webhooks/github	GitHub PR, check-run and push events (X-Hub-Signature-256 verified)	—
POST	/webhooks/datadog	Datadog monitor alerts, routed by ?token=	—
POST	/webhooks/inbound	Generic structured event (tab, title, message, severity), routed by ?token=	—

SCIM

SCIM is served at https://api.devbar.app/scim/v2 (not under /api/v1) and authenticated with the SCIM token generated for the organisation.

Method	Path	Description	Auth
GET	/scim/v2/Users	List SCIM users	Required
POST	/scim/v2/Users	Provision a new user	Required
GET	/scim/v2/Users/:id	Get a SCIM user by ID	Required
PUT	/scim/v2/Users/:id	Replace a SCIM user	Required
PATCH	/scim/v2/Users/:id	Partially update a SCIM user	Required
DELETE	/scim/v2/Users/:id	Deprovision a SCIM user	Required

WebSocket

Method	Path	Description	Auth
GET	/ws	WebSocket upgrade endpoint for real-time events	Required

Request / Response Examples

Curl examples for the most commonly used endpoints. Replace bearer tokens with your own.

Authentication

POST /api/v1/auth/login

Request

curl -X POST https://api.devbar.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "s3cret!"}'

Response (200)

{
  "data": {
    "user": { "id": "usr_abc123", "email": "[email protected]", "name": "Jane Doe" },
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }
}

Errors

401 Invalid credentials
429 Rate limited (10 req/15min)

POST /api/v1/auth/register

Request

curl -X POST https://api.devbar.app/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "[email protected]", "password": "s3cret!"}'

Response (201)

{
  "data": {
    "user": { "id": "usr_abc123", "email": "[email protected]", "name": "Jane Doe" },
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }
}

Errors

409 Email already registered
422 Validation error (weak password, invalid email)

POST /api/v1/auth/refresh

Request

curl -X POST https://api.devbar.app/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "dGhpcyBpcyBhIHJlZnJl..."}'

Response (200)

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "bmV3IHJlZnJlc2ggdG9r..."
  }
}

Errors

401 Invalid or expired refresh token

Tokens

POST /api/v1/tokens

Request

curl -X POST https://api.devbar.app/api/v1/tokens \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"label": "CI Pipeline"}'

Response (201)

{
  "data": {
    "token": { "id": "tok_xyz789", "label": "CI Pipeline", "token_prefix": "dvb_live_abc", "is_active": true },
    "raw_token": "dvb_live_abc123..."
  }
}

Errors

401 Unauthorized
400 Missing or too long label

GET /api/v1/tokens

Request

curl https://api.devbar.app/api/v1/tokens \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200)

{
  "data": [
    {
      "id": "tok_xyz789",
      "label": "CI Pipeline",
      "token_prefix": "dvb_live_abc",
      "is_active": true,
      "last_verified_at": "2026-04-23T18:30:00Z",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ]
}

Errors

401 Unauthorized

Billing

GET /api/v1/billing/plans

Request

curl https://api.devbar.app/api/v1/billing/plans

Response (200)

{
  "data": [
    { "slug": "solo", "name": "Solo", "price_monthly": 8, "max_seats": 1 },
    { "slug": "team", "name": "Team", "price_monthly": 12, "max_seats": 100 },
    { "slug": "enterprise", "name": "Enterprise", "price_monthly": 15, "max_seats": 1000 }
  ]
}

POST /api/v1/billing/checkout

Request

curl -X POST https://api.devbar.app/api/v1/billing/checkout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"plan": "solo"}'

Response (200)

{
  "data": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
    "provider": "stripe"
  }
}

Errors

401 Unauthorized
400 Already subscribed to this plan

Announcements

GET /api/v1/announcements

Request

curl https://api.devbar.app/api/v1/announcements \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200)

{
  "data": [
    {
      "id": "ann_001",
      "title": "v1.3.0 Released",
      "body": "Free trial and storage provider choice now available.",
      "created_at": "2026-04-20T10:00:00Z"
    }
  ]
}

Errors

401 Unauthorized

Webhooks

POST /webhooks/inbound accepts a structured JSON payload and routes the event to the user, org, or team associated with the token. The token query parameter is required and determines routing scope.

Request payload

{
  "tab": string,          // required — the source tab/platform label (e.g. "github", "pagerduty")
  "title": string,        // required — short event title shown in the menu bar
  "message": string,      // required — event body / detail text
  "severity": string      // optional — "info" | "warning" | "error" (default: "info")
}

POST /webhooks/inbound

Request

curl -X POST "https://api.devbar.app/webhooks/inbound?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tab":"alerts","title":"Deploy failed","message":"Step build failed on main","severity":"error"}'

Response (200)

{
  "received": true
}

Errors

400 Invalid JSON or missing title