REST API

Authentication

Create a token in Settings → Tokens (or with buildfy tokens create) and send it as Authorization: Bearer bfy_… on any /v1 route. Tokens start with bfy_, are stored hashed, can be bound to one workspace or all of yours, and can expire. Creation and revocation are written to the workspace audit log; removing a member revokes their tokens for that workspace.

# Create a token in Dashboard → Settings → Tokens, or:
buildfy tokens create --name ci --scopes read,deploy --expires 90d

curl -s https://api.buildfyio.com/v1/orgs/$ORG_ID/projects/$PROJECT_ID/deployments \
  -H "Authorization: Bearer $BUILDFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"env":"production","branch":"main","trigger":"manual"}'

Permissions

A request the token is not allowed to make gets a 403 naming the missing permission; a revoked or expired token gets a 401.

HTTP/1.1 403 Forbidden
{
  "code": "insufficient_scope",
  "message": "insufficient_scope: env:write — this token does not have the \"env:write\" permission.",
  "details": { "requiredScope": "env:write", "tokenScopes": ["read", "deploy"] },
  "status": 403
}

GitHub Actions

Store a read,deploy token as the BUILDFY_TOKEN repository secret. Nothing else from your account goes into CI, and revoking the token is the whole rotation.

# .github/workflows/deploy.yml
name: Deploy to Buildfyio
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger production deploy
        env:
          BUILDFY_TOKEN: ${{ secrets.BUILDFY_TOKEN }}   # read,deploy is enough
        run: |
          curl --fail-with-body -s \
            https://api.buildfyio.com/v1/orgs/${{ vars.BUILDFY_ORG_ID }}/projects/${{ vars.BUILDFY_PROJECT_ID }}/deployments \
            -H "Authorization: Bearer $BUILDFY_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{"env":"production","branch":"main","trigger":"manual"}'

      # Or with the CLI, which also waits for the build to finish:
      # - run: npx @fyio/buildfyio-cli deploy --prod --branch main
      #   env: { BUILDFY_TOKEN: ${{ secrets.BUILDFY_TOKEN }} }